Skip to content
loading...

re: Code for Humans VIEW POST

FULL DISCUSSION
 

unless it is a framework, module, class, method, variable names should be self documenting without need of additional documentation

Maybe I just don't understand what you mean here, but I would say especially in a framework you need to be careful with naming things and making code self-documenting. Frameworks just need documentation in addition to this, so that the flow of the framework can still be followed even without looking at the source directly.

One other thing I would add in the documentation section: Code (even messy code) will tell you what's going on, so comments should describe the why, not the what.

 

What I meant to say is, unless it's a framework, self-documenting code is enough, no need to have comments most of the time.
Frameworks too would follow the naming conventions, and on top of this they would also have the documentation/user-guides and comments that explicitly state the intent of code.

I would avoid adding too many comments within the domain/application specific projects, except when these are actually needed, like when there's a special branching instruction to handle rare edge case. The Why not the What.

I will try to rephrase this for more clarity. Thanks :)

code of conduct - report abuse