Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
How much technical (for future developers) documentation is enough? Is there a ratio between hours coding and hours documenting that's appropriate?
Papadimoulis argues that you should
produce the least amount of documentation needed to facilitate the most understanding,
Is that a good guideline, or are there specific things I should be creating?
How about some hallway usability testing? Show the code and documentation to a developer unfamiliar with the project. When you can do that without an overwhelming urge to explain something while watching them review the code, you have enough.
La perfection est atteinte non pas quand il n’y a plus rien à ajouter, mais quand il n’y a plus rien à retirer.
Antoine de Saint-Exupéry
I've been thinking about this topic for a while.
My conclusion is - it's not a matter of quantity, but of quality and context.
For example, a proper project structure beats comments explaining where the files are located (implementation vs. intension)
Similarily, classification to clarify context beats naming (Id on a Patient -> Patient.Id).
I believe DDD has a say in good documentation - classification provides context, context creates boundaries and boundaries lead to intentional implementations (this is where this belongs, rather than it needs to exist).
Code in itself isn't good enough to be considered documentation. The problem in most cases doesn't reside in the fact that the codes' working is commented or not commented, but rather the driving force (domain logic) isn't.
We sometimes forget who's boss - if the code changes, the domain logic or reasoning shouldn't, but if the domain logic or reasoning changes the code definitely will.
Consistency is very important also - convention by itself is useless if it isn't consistent.
Design patterns aren't just 'good practice' - it's lingo us developers should understand. Telling a developer to add a new type to a Factory is better understood than to add a new type to a method (where context and consistency is weak or missing).
Half the struggle is familiarity.
On a side note, API's which seem to favor a lot of documentation are also very domain and context sensitive. Sometimes duplicating functionality isn't evil (same thing, different contexts) and should be treated as separate.
In terms of commenting, it's always good to point out the domain logic behind the reasoning.
For example, you are working in the medical industry. In your method you write "IsPatientSecure = true;"
Now, any decent programmer can figure out that the patient is being marked as secure. But why? What are the implications?
In this case the patient is an inmate that was transferred securely to an off premises hospital. Knowing this, it is easier to imagine the events that lead up to this point (and perhaps what still needs to happen).
Maybe this post seems philosophical at best - but remember that it is 'reasoning' or 'logic' that you are writing about - not code.
I agree with the Papadimouslis quote. The source code can speak for itself, but the code can't tell you why it exists, how it should be used, and how the code should behave.
I don't know a good ratio.
I inherited hundreds of lines of code with very little documentation. It became difficult for me to understand why the code was written. After I found out why the code was written, I had to figure out how to use the code. After I found that out, I had to understand how it is suppose to behave so I can support and maintain the code.
Just from experience, don't make comments too specific or you will end up having to maintain the actual code AND the documentation. It is a nightmare when the documentation and code are out of sync.
Enough to make you stop second guessing yourself.
If at any time during your work you're like "hmm maybe I should document this", go ahead and do it. Then, if you've written some documentation and you're like "maybe I should explain this more", go ahead and do that.
Rinse-repeat until that feeling goes away.
I've found that a risk-driven approach such as that presented in George Fairbanks' book Just Enough Software Architecture works extremely well for understanding how much documentation is enough. You can read the section which presents this concept (chapter 3) on his website but the main idea is to:
To help calibrate concerns so you can prioritize risks I've found it helpful to identify a couple of goals known as the Threshold of Success, that is the minimum set of goals your team thinks a "successful" project must achieve. From a documentation perspective an example ToS might be something like "A developer should be able to build a simple plug-in within 4 hours of picking up the framework for the first time."
Now identify some risks. With the system you've built (or are building) what are the things that worry your team most? Phrase these as risk statements. I like the SEI's condition-consequence style but there are others. Examples:
Now as a team, prioritize the risks. Multi-voting works extremely well.
Mitigate the top priority risks, and repeat starting with identification until the risk of your project failing (defined by the Threshold of Success) is within a tolerable limit. Generally this will mean you'll have some risks that the team agrees are not much of a concern. Keep in mind that you probably won't want to mitigate all the risks. An example mitigation strategy for the last risk above might be to create a tutorial.
As little as possible, but as much as is necessary
I can't remember where & when I first heard that, but it's a maxim with many applications.
The more complex the technology or the application, the more documentation would be needed (obviously), but clearly you don't want to waste time going overboard.
JohnFx's 'hallway test' is sound. But trust yourself; you developed the code, and so you of all people should have a feel for the elements that need extra attention, and the elements that will be obvious to all. Think of the struggles you had developing the code and you'll likely have an idea what another developer will see when they look at your code.
Forget any relationship between effort spent coding and effort spent documenting.
I believe you cannot put this into exact rules. The reason for documenting is to provide the knowledge not easily gathered from the raw code in a form so others can understand and perhaps even maintain said raw code.
Hence the only way you can tell if you have documented enough, is to ask the target audience if it is good enough. I believe the "peer review" process is very good at doing this up front. Notice how much explaining is needed to make your peer understand what you are talking about, and work to minimize that.
If you have never done this before, you cannot estimate how much work it will take, but after a few iterations you will get a much better idea of how much is needed.
