15
Comments
  • 1
    Partially agree: it would require you to read the entire code, but often you just want to get/understand just a dedicated part of it. I just had this case a few day ago where I had to study an entire f****** Android App in order to extract the process behind. This costs me a f****** whole day. A simple process diagram would have saved me so much time. At the end I was creating the process diagram ans everyone was just like..."ohhh ahhh finally we see the big picture sad that we didnt offered that from the beginning". Of course code must self explaining, but an additional docu is so much of help
  • 1
    Code should be clear enough that it is practically self documenting.

    However, there are always parts that comments can clairify the context of the code and enhance or clairify what is as clear as possible with the code itself. Your future self or code maintainer will thank you.

    Undocumented or commentless code is poor code. Having said that, the balance is that code that has too many or extremely obvious comments is also poor code.

    Middle way and moderation in all things. Code that documents itself and documentation that enhances the code or clarifies contexts is the way.
  • 1
    Comments only public part API but use complete variable and function name
Add Comment