How much or how little do you comment or document your code?

I think this very easily becomes difficult to keep track of what is what. Also having all the code in the document makes everything else more messy. If you just want to describe what is going on then you usually don’t want all the code as it tends to hide the important bits.

I personally think they complement each other. Having the types does not really describe what is done with them.

Just to be difficult. :wink:

2 Likes

I admit to only having written small systems and not to the extend of TeX or LCC with literate programming. I found it forces you to think about your design and overall code and laying things out to be readable by humans.

With the shift towards meaningful function names, I found @spec usually sufficient to understand how to use a function. In my experience if you were careful avoiding side-effects it is possible to drop a replacement function by just honoring the @spec contract.

Yes I do hear the calls of strong type system yet again…

I believe that most documentation represents a failure to express intentions with the code itself. Nearly all software can be written in a self documenting manner, with little exception (e.g., handling of a nuanced and complex 3rd party API over which you have no control, etc).

Anytime you feel the need to write documentation about your functions, or within a function, or for a module, re-evaluate two things:

  1. Is this module/component’s responsibility clearly defined?
  2. Can variables and function names be re-written to better express what everything is doing? Prefer long names over code that is difficult to read quickly by others.
1 Like

As you may have guessed I don’t agree with you here. Code without documentation can at best say what it is doing, not why and what is the overall intent. Also long variable and function names may be informative but they do tend to hide the structure of the code and make it more difficult to understand.

This pretty much says it all Real Programmers Don’t Write Documentation. It is a very funny series though it hasn’t been around for a while.

3 Likes

I would then state that the system your module lives in needs better self documentation. It is achievable, even with large scale and highly sophisticated systems, to be entirely self documenting.

This also includes the test suite as self documentation, as mentioned by @dogweather above. Test structure is important, and titles of tests can reveal lots of information (especially when considering the larger test suite structure).

It often takes a lot of practice, discipline over time, and constantly thinking about the long term intentions of the component of the system youre working on. The more you focus on self documentation, the more natural it will feel. Soon you will regard all comments as an opportunity to better self document the underlying code, and have the current system be better named to reflect the biz logic therein. That “0-1%” rule is totally achievable with practice.

I think this would be much harder without code reviews, so having a 2nd person (or more!) read your code is helpful.

And of course Im referring to “comments in code”, or documentation that compiles/ships with your non public software. OSS, consumer-facing APIs, frameworks, and various forms of libraries or plugins certainly need human-facing documentation.

Generally, I prefer self documenting code over commenting. So I tend to write very few comments and focus on naming things and abstracting functions in a sensible way.

As far as documentation - on personal projects I document only where I need to. Most of the Elixir I write currently tends to be customer facing, so in those cases I document a lot because I see it as one of the things I am offering my client. In that case I treat documentation much like a solid test suite.

1 Like

This thoughtbot blog post has a great walkthrough with code examples. I especially like this quote:

Comments are a code smell which means “something may be improved here and we should dig deeper to see if that’s true.” In this case, the smell is “hey something is probably more complicated than it needs to be.”

I hadn’t noticed this line the first time around. I would say that this represents having chosen the wrong name. The goal of using role or intention revealing names is the exact opposite - to reveal the structure of the public interface, and make it easier to understand.

1 Like

Universal rule: keep everything fanatically short. Your code shouldn’t be a YouTube channel where you get to excitedly greet people who stop by. Keep it professional.

A few other rules I follow:

  1. Descriptive module and function docs. If you are the guy who just installed the library and wants to get something done in 10 minutes and move on, what would you like to read on the GitHub README page? That’s your benchmark.

  2. Usual structure should be: goal of the module/function, links to possible error conditions, caveats and tradeoffs (f.ex. this function does not create the file if it doesn't exist). If it is important, clearly state dependencies.

  3. Comments are indeed a code smell 90% of the time. Elixir can help you with that:

    • Sparingly use case or cond – use function heads wherever possible – this has the added benefit of allowing you to pattern-match the parameters and enforce contracts early. Additionally, this leads to shorter functions which in turn improves readability (not an universal rule but it’s true often enough; big pattern-matching heads can become a problem but it’s my observation that’s rarely happening in most projects).
    • Sometimes you have slightly WTF code – like a function that always returns an {:ok, value} tuple and you have to pipe that to elem(1) to get the value before you feed it something else. It’s okay to put something like # unwrap the :ok tuple in the code line to make the intention clear.
    • Long function names – I agree with the others. Work hard on your English expresiveness, it’s a solid investment that pays off everywhere else, not only in programming.
  4. Many tests make both docs and comments superfluous. If your tests are descriptive and clearly outline the contract of your code then that can save you a lot of English copywriting.


…It’s kind of ironic how this comment didn’t turn out to be short at all though. :lol:

1 Like

http://antirez.com/news/124

An interesting blog regarding code comments.

2 Likes

I actually do the reverse. :upside_down_face:

I write the comments and or documentations first. Much like talking to myself before writing the code.

It’s just to confirm and scream the intention to my mind and my code-pairing partner. What am I (are we) supposed to write here?

This way I could easily name my modules, classes and methods, flow of logics, and manything else.

Whenever I stumble upon a method or module, when I try to update it, I always update the comment/doc as well. Usually I update the comment/doc first. Again, just to confirm my intention strongly.

It doesn’t matter where you put your documentation, in the code or in another media, when they are out of sync, it would be bad. It is developers task to make it sync. But I prefer it in my code.

Some say that comments/docs in code is convoluted and harder to read. Just use a text editor capable on hiding them.

2 Likes

That’s fair. I sometimes do the same but rarely.

My problem is that, as you said, code and docs/comments can very quickly get out of sync. Especially if you code a new feature or a library, things can be changed several times an hour.

For a more mature codebase I would use your approach but when I am bootstrapping things I found it to be an extra overhead.

But hey, I am not arguing. I know this helps people put their thoughts in order. It’s just that I tick another way. :slight_smile:

Documentation-Driven-Development. We can call it DDD. :joy:

Although with DDD’s attention to language, it’s probably not that far off.

1 Like

yea, much like rubber duck debugging, it helps me though.

1 Like