What's your excuse?

The code should be self documenting!!

Docs always become outdated 😜

///<summary >
/// How it's used.
///</summary>
void DoStuff()
{
// why it's done
int what = it.Does();
}

I don't want to lose my job

I program in Ruby

@CWins I was thinking to make a better documentation tool. Like jsdoc:
// #param name:obj type:object
And it should generate MSDN-like pages

@CWins won't summary explain "what it does"? Or do you include that in "how it's used"? Or not?

@Alfer
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.

@robzombie111
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.

Two articles that i found readworthy.

https://dev.to/andreasklinger/...

https://standards.mousepawmedia.com/...

@mstrange88 Once you get the hold of it, its not that hard!! Use descriptive method names and be like a storyteller. Something like:

def replace_username_with(email)
...
End