3 ms·
I think the one thing we do wrong with code is when we document it, we write what the function does. Code is largely self-documenting and this because stale qui
by snarf21 6y ago
I think the one thing we do wrong with code is when we document it, we write what the function does. Code is largely self-documenting and this because stale quickly anyway.
IMO, the thing we should be doing is documenting WHY this function needs to exist. That is the question that is hard to answer three years later.
- loopz 6y agoI like your comment, but for the wrong reason: Explaining what a method DOES, goes against encapsulation principles. It creates coupling to implementation details, when what should be provided is just the interface. Any explanation can be exposed in business domain logic and documentation.
- Jtsummers 6y agoThere are multiple pieces of documentation. Documenting what a method does is one of them, but primarily intended for maintainers of the system. Documenting its interface is meant for its users. Both have great value, but at different times and to different people.
- loopz 6y agoIndeed, was thinking the same thing while posting. In practice though, I've mostly encountered lack of comprehensive developer docs, or they became outdated years ago. Most devs will point to source itself for documentation, unless for critical or certified software. If not the latter, the internal logic is usually scattered and not cohesive. So need to check dozens of files for each hypothesis about the original intentions and context.
- tmaly 6y agoI am working on some code I last touched 12 years ago. I think good documentation is essential, it saves time in the long run. Knowing the why is very helpful.