A checklist for abstractions

12/27/2022

A checklist for abstractions

12/27/2022

A checklist for abstractions

12/27/2022

A checklist for evaluating whether you’re creating good, usable abstractions or not.

Does your API operate at a consistent level of abstraction — do you avoid having some methods that require users to pass you SQL statements and others that encapsulate this detail, for example?
Do your methods generally have two or fewer parameters (more parameters making it increasingly hard on users to intuitively understand the method)?
Do your methods have succinct but communicative names like “CreateEntry(Entry entryToCreate)” as opposed to the needlessly verbose (“CreateRecordThatIsGoingToGoInTheDatabase(Entry entry)”)? On the opposite end of the spectrum, are your names hard to type and remember or weirdly succinct such as (“CE(Entry e)”)?
Do your methods lie? Does “CreateEntry(Entry entryToCreate)” actually delete an entry, or perhaps less egregiously, create an entry sometimes, unless the entry has a certain flag set true, in which case it quietly fails?
Do you avoid forcing weird details on your clients, such as asking them to store boolean flags?
Do you avoid multiple return values (i.e. out/ref parameters?)
Do you somehow communicate what exceptions your methods might throw?
Do you limit the number of methods per class so that reading through the documentation or IDE assistance is not painful?
Do you avoid forcing your clients to violate the Law of Demeter? To get “D”, do you force your clients to call getA().getB().getC().getD();?
Do you practice command query separation in your public API?
Do you limit or eliminate exposing public state, and especially flags?
Do you limit temporal couplings that force your clients to call your methods in a specific order?
Do you avoid deep inheritance hierarchies that make it unclear where the members of the public API actually come from?
Do your publicly exposed classes have a single, obvious responsibility — do you avoid exposing swiss-army-knife classes with a mish-mash of different functionalities?

Follow for more

My writing is also posted on Medium, where you can follow to receive notifications for new posts, comment, and more: https://michael-flores.medium.com/

A checklist for evaluating whether you’re creating good, usable abstractions or not.

Does your API operate at a consistent level of abstraction — do you avoid having some methods that require users to pass you SQL statements and others that encapsulate this detail, for example?
Do your methods generally have two or fewer parameters (more parameters making it increasingly hard on users to intuitively understand the method)?
Do your methods have succinct but communicative names like “CreateEntry(Entry entryToCreate)” as opposed to the needlessly verbose (“CreateRecordThatIsGoingToGoInTheDatabase(Entry entry)”)? On the opposite end of the spectrum, are your names hard to type and remember or weirdly succinct such as (“CE(Entry e)”)?
Do your methods lie? Does “CreateEntry(Entry entryToCreate)” actually delete an entry, or perhaps less egregiously, create an entry sometimes, unless the entry has a certain flag set true, in which case it quietly fails?
Do you avoid forcing weird details on your clients, such as asking them to store boolean flags?
Do you avoid multiple return values (i.e. out/ref parameters?)
Do you somehow communicate what exceptions your methods might throw?
Do you limit the number of methods per class so that reading through the documentation or IDE assistance is not painful?
Do you avoid forcing your clients to violate the Law of Demeter? To get “D”, do you force your clients to call getA().getB().getC().getD();?
Do you practice command query separation in your public API?
Do you limit or eliminate exposing public state, and especially flags?
Do you limit temporal couplings that force your clients to call your methods in a specific order?
Do you avoid deep inheritance hierarchies that make it unclear where the members of the public API actually come from?
Do your publicly exposed classes have a single, obvious responsibility — do you avoid exposing swiss-army-knife classes with a mish-mash of different functionalities?

Follow for more

My writing is also posted on Medium, where you can follow to receive notifications for new posts, comment, and more: https://michael-flores.medium.com/

A checklist for evaluating whether you’re creating good, usable abstractions or not.

Does your API operate at a consistent level of abstraction — do you avoid having some methods that require users to pass you SQL statements and others that encapsulate this detail, for example?
Do your methods generally have two or fewer parameters (more parameters making it increasingly hard on users to intuitively understand the method)?
Do your methods have succinct but communicative names like “CreateEntry(Entry entryToCreate)” as opposed to the needlessly verbose (“CreateRecordThatIsGoingToGoInTheDatabase(Entry entry)”)? On the opposite end of the spectrum, are your names hard to type and remember or weirdly succinct such as (“CE(Entry e)”)?
Do your methods lie? Does “CreateEntry(Entry entryToCreate)” actually delete an entry, or perhaps less egregiously, create an entry sometimes, unless the entry has a certain flag set true, in which case it quietly fails?
Do you avoid forcing weird details on your clients, such as asking them to store boolean flags?
Do you avoid multiple return values (i.e. out/ref parameters?)
Do you somehow communicate what exceptions your methods might throw?
Do you limit the number of methods per class so that reading through the documentation or IDE assistance is not painful?
Do you avoid forcing your clients to violate the Law of Demeter? To get “D”, do you force your clients to call getA().getB().getC().getD();?
Do you practice command query separation in your public API?
Do you limit or eliminate exposing public state, and especially flags?
Do you limit temporal couplings that force your clients to call your methods in a specific order?
Do you avoid deep inheritance hierarchies that make it unclear where the members of the public API actually come from?
Do your publicly exposed classes have a single, obvious responsibility — do you avoid exposing swiss-army-knife classes with a mish-mash of different functionalities?

Follow for more

My writing is also posted on Medium, where you can follow to receive notifications for new posts, comment, and more: https://michael-flores.medium.com/