Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple APILearn More
The code should be self documenting!!
Docs always become outdated 😜
/// How it's used.
// why it's done
int what = it.Does();
Eriqdev1933yI don't want to lose my job
I program in Ruby
Of course theres an overlap. I chose "How it is used" because it emphasizes the perspective of the user.
I think perspective is important when writing documentation. Summary-docs are seen in a tooltipp by dev who use that component, while comments in code are seen by devs who debug/change the code.
While it is true that changes in code can make the comments lie, the reason for change in code are often bugs which means, that the code does not match it's intent and it's hard for the next developer to make code fit the intent, if there is only code.
A well done summary can tell what a piece of code is intended to do and how it is used.
I'm all in on good naming and readable code, and comments should not repeat that, but they can add information the code does not and can not give, which is intent and knowledge that is not obvious, like some other API or LIBs behaviour that requires code, that seems suboptimal.
@mstrange88 Once you get the hold of it, its not that hard!! Use descriptive method names and be like a storyteller. Something like: