2025 Public Training Schedule
June 23 26, 2025 – Agile Analysis and Design Patterns – Half-Day Sessions Online
July 22 – 25, 2025 – Agile Analysis and Design Patterns – Half-Day Sessions Online
Follow me on Twitter:
Blog Post Categories
- Announcements {19}
- Articles {2}
- Bits and Pieces {74}
- Blogosphere {1}
- Bonuses {2}
- Build in Small Batches {27}
- Collaborate {38}
- Create CLEAN Code {34}
- Implement the Design Last {11}
- Integrate Continuously {30}
- Off-Topic but Interesting {3}
- Rants {82}
- Refactor Legacy Code {24}
- Say What, Why, and for Whom Before How {22}
- Seven Strategies {38}
- Specify Behaviors with Tests {17}
- Write the Test First {27}
Archives
Privacy Policy
(c) 2025 To Be Agile
- September 28, 2016 ( 1 comments )
- Bits and Pieces
In my last blog post, Comments on Comments, I was perhaps a bit harsh on the practice of comments in code. What I meant was that excessive what comments, which are comments that explain what the code is doing, are a possible indicator that the developer who wrote them was uncertain that the code could speak for itself.
There are other reasons to write comments in code. Sometimes it’s clear what we’re doing but not always clear why we’re doing it. Why comments, as I call them, say why something is being done in code. This could be because of a federal regulation or it could be expressing how a design comes together at a higher level. These kinds of comments can be breadcrumbs to the people maintaining the code so that they can get a sense of what is actually happening and maybe call out some design features that aren’t entirely obvious. But don’t resort to teaching your reader things they should already know.
Well-encapsulated code is often presented outside of the context in which it lives. This can make it difficult to understand, so visualization tools can be very helpful.
The domain model should be represented in the objects’ relationships to each other in the system. This makes the system understandable to other people. But in a lot of systems I’ve seen there were huge swaths of missing objects in their domain model. Sure they call out the important ones, the ones that are most visible, but many of them are actually made up of many smaller objects that they haven’t called out. Nor have they called out the main collaborator objects that their main objects interact with. This creates a shallow domain model and it forces developers to read every line of code in order to understand a system.
I don’t believe developers should have to read all of my code in order to understand what it does. I believe developers should have to read my method signature and understand what my method does. I don’t like surprises so I keep my APIs clear and to the point. If I’m developing a library or a framework, I will spend extra attention on writing good developer documentation and probably provide a range of good examples through unit tests. Developers can get a good sense of how to use my APIs but I’ll never bore them with lots of superfluous text.
{1 Comments }
Previous Post: « Comments on Comments
Next Post: One-Click Builds »
I have always been a proponent of documenting (somewhere) the “why” of a design/implementation. I can remember several occaisions when someone looked at some “fugly” code, decided to redo it and find out 75% of the way through that they didn’t understand the scope of the issue that led to the original code. The end result is a “learning experience” that results in lots of wasted time and not much change to the original code. Some explanation of “why” that implementation was chosen (especially if the original author knew it was “fugly”) would have been a big help. If requirements are the “what” and design is the “how”, the key 3rd leg is often “why” (this design rather than another).