These are my thoughts about
Dennis Doomen's post on documenting code...
I dislike comments in code. They represent a failure on the author's part to express an idea in the language they're using (C#, Java, etc.). That doesn't mean I never use them, or find them completely useless. They should be the exception not the norm.
I use the class, method, and parameter names to infer what the code will do. If I have questions using an API, I try to write some form of test which captures what I want to do. If I want to know more about the implementation details, I'll go look. I think well named components and a suite of tests do a lot more to document code. They also don't go stale. I'll also favor writing tests around my code to demonstrate how it works or what it does.
When I need to see how a library works, I'll look for code examples. The online docs, and available online resources are my resources. It's rare I'll simply use the comments on the public/protected members.
Inline comments are a real red flag to me. Way too often I see them when a dev hasn't expressed themselves well enough in the language they're using. These should be really, really, really rare. The nice thing about these being so rare is they stand out. Most of the devs I've worked with have learned that an inline comment is a danger sign that we've left for one another. They also tend to disappear as a code base matures.
Commit messages are stupid important. I don't know if I consider this documenting the code. It's more a history of what happened and why it happened. It's helpful if the commit messages focus on what the changes did: "Added login screen," or, "updated main landing screen to show user name."
There's my $.02.
