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]
This is a single comment view full discussion

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.

code of conduct - report abuse