// No Comment

Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.

- Uncle Bob, Clean Code

I’ve started processing life in code. Major decision-making is determined by a minimax algorithm and instructions are delivered in `if-else` statements.

(defn add-comments-to-code
  [comment]
  (try 
     (express-comments-in-code comment)
     (catch Exception e
        (write-comments comment)

Hence, the Clojure code block above is not really code, it’s pseudo-code representing how we should approach commenting. We should first attempt to express our comments in the code itself , which is regarded as the single source of truth and accuracy. Only when we are unable to do so (a “failure to express ourself in code”) should we actually leave comments. I used to liberally sprinkle comments to organize my code, but decided to just make things smaller and more readable and eliminate commenting altogether.

• Why do comments suck? As code changes, comments become separated or irrelevant or inaccurate. Then, they mislead you.
• When are comments bad? 
  - If they’re an excuse for bad code or hacks
  - If they lie or mislead
  - If they’re used to “log entries.” These days, version control systems handle that splendidly.
  - If they add noise, as in they simply reinstate the code.
  - If they are used as a “banner” to gather certain functions together. I’m guilty of this one.
  - If they are used to indicate closing braces. I had an instructor actually tell me we should do this /side-eye
  - If they are used as attributions or bylines
  - If they are used to comment-out code
• When are comments good? If they’re used for legal reasons. If they provide clarification (readability), information, or intent (especially if there are multiple solutions to a problem — it may help to understand why something was done). I also use comments for interim purposes. For instance, `TODO` comments are used for parts of the code that I’d like to troubleshoot, but cannot do at the moment. It may be a reminder to delete a feature or request for someone else to look at the problem. I also use commenting extensively as a way to introduce new features, without having to alter working functions. This is more for readability (and the fact that I hate undoing things). I simply duplicate and comment-out tested, working functions. Then, I designate an area in my code as a “sandbox” with altered versions of those functions. Mind you, none of this ends up in the final version of my code.

; (defn original-method
;   []
;   (something-here))

;;;;;;;; SANDBOX ;;;;;;;;

; I test methods in here and comment out things as I please.

(defn original-method
   []
   (something-else-here))

;;;;;;;; SANDBOX ;;;;;;;;

It seems like certain languages have a way to handle systematize comments. One example provided by Clean Code was using comments as a warning (e.g. if the test takes a really long time to run). In the instance of a test case in JUnit, you can use the `@Ignore` attribute with an explanatory string. Also, Clojure implements docstrings, which are optional strings used to describe a function.

TL;DR Don’t comment when you absolutely don’t need to.