DEV Community

Discussion on: Don't document your code. Code your documentation.

Collapse
 
dgbrewer1989 profile image
David Brewer

Great post!

When I first got into development I was really confused by the concept of not adding documentation to code. In school I was taught to always comment everything and always have documentation in code. On top of that I worked as an automation engineer for a while where each line had to be commented to explain what it was doing. Which in hindsight, was terrible to read and scan.

I understand this concept now and really it's just easier this way. The only time comments are really added to a project that I've seen are when a special work around is added for a bug in a library (external dependency), which includes a TODO to come back and update the code when the bug is fixed.

For me and the company I work for, we document our functionality and how API's are supposed to work in a common space that isn't in code.