Skip to main content
Commonmark migration
Source Link

I find sticking to Bob Martin's approach to this, from Clean Code, usually solves the problem of whether you think you're over commenting or under commenting and leaving out documentation:

We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

 

...the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

So in other words, is your code is self explanatory without the documentation? There's no set rule for it (unless you work for somebody like Microsoft whose documentation is publicly accessible), it's mostly down to helping the future reader of the code which is often you.

I find sticking to Bob Martin's approach to this, from Clean Code, usually solves the problem of whether you think you're over commenting or under commenting and leaving out documentation:

We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

 

...the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

So in other words, is your code is self explanatory without the documentation? There's no set rule for it (unless you work for somebody like Microsoft whose documentation is publicly accessible), it's mostly down to helping the future reader of the code which is often you.

I find sticking to Bob Martin's approach to this, from Clean Code, usually solves the problem of whether you think you're over commenting or under commenting and leaving out documentation:

We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

...the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

So in other words, is your code is self explanatory without the documentation? There's no set rule for it (unless you work for somebody like Microsoft whose documentation is publicly accessible), it's mostly down to helping the future reader of the code which is often you.

Source Link
Chris S
  • 899
  • 6
  • 11

I find sticking to Bob Martin's approach to this, from Clean Code, usually solves the problem of whether you think you're over commenting or under commenting and leaving out documentation:

We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

...the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

So in other words, is your code is self explanatory without the documentation? There's no set rule for it (unless you work for somebody like Microsoft whose documentation is publicly accessible), it's mostly down to helping the future reader of the code which is often you.