{"id":73,"date":"2024-02-20T15:41:23","date_gmt":"2024-02-20T15:41:23","guid":{"rendered":"https:\/\/permutationcity.co.uk\/bp\/?p=73"},"modified":"2024-05-30T20:35:03","modified_gmt":"2024-05-30T20:35:03","slug":"no-comment-code","status":"publish","type":"post","link":"https:\/\/permutationcity.co.uk\/bp\/2024\/02\/20\/no-comment-code\/","title":{"rendered":"No comment code"},"content":{"rendered":"\n

My last post<\/a> mentioned No Comment Code\nand my initial horror at the idea. I’d not come across it directly before last year. However I think\nI’ve seen it’s influence on some other developers. I’ve done a bit of research but will be using \nDon’t Write Comments<\/a> and\nTo Comment or Not to Comment<\/a> as my primary\nreferences here.<\/p>\n\n\n\n

What they say<\/h2>\n\n\n\n

There doesn’t seem to be a unified No Comment Code methodology just a general feeling that comments have\nproblems. That has lead some people to write (almost) no comments and others to limit their usage.\nThere also seems to be a distrust of existing comments so they don’t bother to read them.<\/p>\n\n\n\n

Their problems with comments are:<\/p>\n\n\n\n

    \n
  1. Writing comments takes time but does not influence runtime behaviour.<\/li>\n\n\n\n
  2. Comments cannot be tested and therefore may be wrong.<\/li>\n\n\n\n
  3. Comments are often not properly maintained and therefore may be wrong.<\/li>\n\n\n\n
  4. Comments may be unrelated or offensive.<\/li>\n<\/ol>\n\n\n\n

    Their solution to this is to avoid or limit the usage of comments and let the code speak for itself:<\/p>\n\n\n\n

      \n
    1. Code should be simple to understand.<\/li>\n\n\n\n
    2. Use well named functions and variables to explain operation.<\/li>\n\n\n\n
    3. Break functions and expressions down into simple parts.<\/li>\n\n\n\n
    4. Use explicit types to show what data is.<\/li>\n\n\n\n
    5. Don’t comment when the code can show what is needed.<\/li>\n\n\n\n
    6. Do comment to highlight exceptional circumstances, e.g. thread safety, class states, error conditions, non-obvious performance optimisations, references to underlying algorithms.<\/li>\n\n\n\n
    7. Provide class or API documentation.<\/li>\n<\/ol>\n\n\n\n

      My response<\/h2>\n\n\n\n

      Despite my horror they’re not wrong about the problems.\nI’ve experienced all of these on my projects except the last. I know that one happens as well.<\/p>\n\n\n\n

      I am<\/em> in favour of coding being written to be easy to understand.\nBreaking down large functions into smaller ones and choosing the right name help everyone.\nUsing higher level types rather than basic types adds extra information and can let the compiler check your work.\nIf you have a choice between gaining a little bit of speed or a little bit of clarity I’d recommend the later\n(unless this is a specific performance bottleneck).\nHowever seeing problems with some comments and deciding to throw them all out seems to be an overreaction.<\/p>\n\n\n\n

      While comments can be wrong I think their solution suffers from the same problem.\nHere’s an example starting with the commented form:<\/p>\n\n\n\n

          \/\/ Is letter is a vowel?\n    if (std::range::contains({ 'a', 'e', 'i', 'o', 'u' }, letter))\n    {\n        ...\n    }<\/pre><\/div>\n\n\n\n
      Then the uncommented form:<\/p>\n\n\n\n
          const bool isVowel = std::range::contains({ 'a', 'e', 'i', 'o', 'u' }, letter);\n    if (isVowel)\n    {\n        ...\n    }<\/pre><\/div>\n\n\n\n
      In both cases I can imagine a commit that changes the search but fails to update the comment or identifier:<\/p>\n\n\n\n
          const bool isVowel = std::range::contains({ 'a', 'e', 'i', 'o', 'u', 'y' }, letter);\n    if (isVowel)\n    {\n        ...\n    }<\/pre><\/div>\n\n\n\n
      With every code change the comment or identifier should be reconsidered but it might not be.\nIt’s something developers should watch for in their own code and code review could be used to help with this.\nWe can’t automatically test the correctness of comments or identifiers.\nIf there’s a mismatch between the code, comments or identifiers then it’s time to look at the commit history.<\/p>\n\n\n\n
      My main worry about No Comment Code method is that many people will read the headline\nand stop there. The extra steps to write “better” code will be missed, forgotten or just not done very well.\nTrying to read “standard” code without comments is hard work. Things are done for unknown reasons and build\ntowards unclear result. Even if you can figure out what is happening it may not be what is meant<\/em> to\nbe happening. Without comments there is nothing else to check your reasoning against.\nLetting developers skip comments seems more risky than just bad comments.<\/p>\n\n\n\n
      I have had a problem with too many comments being used for non-comment purposes.\nDocumentation comments can be helpful but they can easily end up taking up so much space that they\ndistract from the code. Having a few lines to describe a function is fine.\nHowever when each parameter, the return value and each related function is mentioned isn’t not.\nTests can also be embedded in comments in some projects.\nHaving tests is great but they can end up being much larger than the code they are testing.\nIn both cases the presentation is a big part of the problem.\nIn all editors I use the comments are shown in the same style whatever they’re actually for.\nAre there any languages out their that support documentation or tests directly?\nPython has Docstrings<\/a> but, again, those are just\nre-using an existing language feature to add documentation.<\/p>\n\n\n\n
      On balance<\/h2>\n\n\n\n
      Writing high quality code is always a good goal but comments can help:<\/p>\n\n\n\n
        \n
      • Explain why something is done.<\/li>\n\n\n\n
      • Give the context for the code.<\/li>\n\n\n\n
      • Summarise sections of code.<\/li>\n\n\n\n
      • Reference full descriptions of specific algorithms.<\/li>\n<\/ul>\n\n\n\n
        I’ve read a lot of code over the years and too many comments<\/em> has rarely been my main problem.<\/p>\n","protected":false},"excerpt":{"rendered":"
        My last post mentioned No Comment Code and my initial horror at the idea. I’d not come across it directly before last year. However I think I’ve seen it’s influence on some other developers. I’ve done a bit of research but will be using Don’t Write Comments and To Comment or Not to Comment as […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","footnotes":""},"categories":[1],"tags":[28,16],"class_list":["post-73","post","type-post","status-publish","format-standard","hentry","category-general","tag-documentation","tag-methodologies"],"_links":{"self":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/73","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/comments?post=73"}],"version-history":[{"count":3,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/73\/revisions"}],"predecessor-version":[{"id":201,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/posts\/73\/revisions\/201"}],"wp:attachment":[{"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/media?parent=73"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/categories?post=73"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/permutationcity.co.uk\/bp\/wp-json\/wp\/v2\/tags?post=73"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}