Don’t document your code. Code your documentation.

Dani Morillas on January 25, 2017

This is one of the great discussions among developers: document or not document your code? Is it worth writing documentati... [Read Full]
markdown cheatsheet

I always try to use good naming conventions for variables, functions, classes, etc.., but I still believe in docstrings for almost every function/method/class. It takes almost no time, it can help you remain focused, and it will help others quickly see what is happening in the code. I avoid using comments within a function/method, unless it is unavoidably convoluted.

I completely agree with this. It makes it so much easier to add someone new to a project.

I feel strong opinions about this subject, I've seen the easiness and welcoming warmth that documented code gives to new people in the code base (and by new I don't mean people with no experience).

I use both, both prose and long and clear variable names that try to speak the intention. I can pick up the code rather easily but my experience is that people don't want to be reading code for the most part unless they absolutely have to.

So as a Python dev I felt that self documented code was the best... but after working in a totally unknown code base in a new language to me... not having prose documentation is hellish.

Do the right thing, try to make comments and variables as simple as possible but not any simpler and also keeping in mind that simplicity is hard and expensive to attain.

Hell sometimes prose and code don't even matter if people won't read either. At that point you even have to consider making video tutorials, talks, conferences, whatever you have to do just to get your point across.

Documentation is hard, but not because of the medium. Some people digest code, others prose, others talks, other classes and a mentor.

And our job is to consider every single one, that is if you want your code to survive.

Well, I think modern coders have confused the reason we should be documenting and commenting. My policy is pretty simple:

  • You should always be able to tell WHAT the code is and does by how you write it (your point.)

  • The WHY (the intent of the code) is rarely something one can figure out in the best of circumstances. This is where commenting comes in - but comment WHY, not WHAT.

  • Documentation, in the literal sense, should be hand-written for your end users. HOW do you use the library/application? I hate it when projects call API docs "documentation," and don't bother with anything else, as it is nigh impossible to learn to use an unfamiliar library from the API docs.

In short, we MUST do all three: code your documentation (WHAT), comment your code (WHY), and document your project (HOW).

I recently read Clean Code for Javascript, it's quite big. But I implement in my coding practices, i think it's for the best, cuz we dev's write's code and projects day in day out, it's for the best to write code which feels like a story and anyone can read it through!

github.com/ryanmcdermott/clean-cod...

While I agree with the general gist of the article, I would live to address this part:

"Extract as much code as you can to methods. Even if you end up having a method with only 3 or 4 lines. Each method should do one thing and only one thing. "

I am not a fan of this part of Clean Code. It is too simplistic on it's advice given - extraction is a good tool, but giving blanket recommendations this way doesn't work.

Let me explain.

I understand where you are coming from, and I did the same for years, but I eventually concluded that my behaviour was leading to worse code, not better. Now, instead, where I used to extract a function, I just tidy it up into a commented block.

In theory, aggressive extraction sounds really good, but pushing for it will lead to premature (i.e. incorrect) abstraction. (Also, since we are talking about a class here, it will also tend to lead to harder-to-track state because it's now spread out over many methods.)

The reason why it leads to premature abstraction is that extracting is really hard to do correctly. It's pretty hard to find the border for what your "one" thing is (and naming it is even harder, sometimes an elegant name obscures), so you are going to fail at doing it a large % of the time. Because the more you extract, the more failed extractions you are going to have, it's important to be careful about extracting and don't use it wildly.

John Carmack, the oculus CTO, writes about a similar thing here:
number-none.com/blow/john_carmack_...

I've seen what happens to comments in code: Nothing. And that's bad. The first coder writes a comment, yeah, great. Then someone makes a quick change to the code... But guess what, the comment doesn't get adjusted. And suddenly the code and the comment are telling two different stories. Happens all the time.

This is one of the reasons I also prefer the clean code approach: Let the code tell the story and restrict the code documentation to the "why". What a method does should be obvious, but the question will be, why it does that. What is the purpose? Why -12 and not -123? etc. The less redundant documentation inside your code, the better.

Of course, if we are talking about a public API or something, a documentation for the user (which can be in the form of many examples) is great to get started, no doubt about that. Also it's not a bad idea to document that structure of your project, the "big picture" to find your way around.

No. While I love some well written code, clear in meaning, it is by no means a substitute for documenting your code. I shouldn't need to dig through what is sometimes hundreds of files and thousands of lines of code just to find out how to do work with a project. It doesn't matter how clear code is, it cannot describe your entire code base, or the far reaching side effects.

I feel disappointed in this article, as I thought it would be about writing a program that takes an AST of your code as input and then outputs literate "pseudocode" that a human can read. For example, if you were to write some FizzBuzz code and feed it into the machine, you would then get the following info:

  1. Set the variable "integer" to equal the input.
  2. Check if "integer" is the modulo of 3, if it is return "fizz".
  3. Check if "integer" is the modulo of 5, if it is return "buzz".
  4. Check if "integer" is the modulo of 3 and the modulo of 5, if it is return "fizzbuzz".
  5. Return "integer".

It might not be good documentation, but it would be interesting documentation.

As for your broader point, I tend to lean towards "Readme Driven Development" - writing the documentation first and then writing the code to match your documentation. You start off with your clean, awesome documentation (knowing what your code is supposed to do beforehand)...meaning you can then focus your time on writing the clean code that matches what your documentation promises.

This is forgetting the (few) times you have to document why you are doing something non-obvious. I otherwise agree documenting the "what" is generally useless and redundant and quickly become stale and error-prone. I however also agree with other commenters that it can be much easier, and not less readable, possibly more, to sometimes add a one line comment rather than extracting a piece of code into its own function/method.

There some cases where I like to put a short summary at the top of a class indicating what it's supposed to do, or what the scope is. Especially if (the name of) the class bears no reference to some familiar pattern in the team.

And I'm all for proper naming and method extraction to avoid comments.

I'm 50/50 on documentation within a method; if you need to document it, it's probably too complicated to begin with. Classes and methods always get XML style documentation, however, and I'm a sucker for a verbose, properly named variable / function.

code of conduct - report abuse