DEV Community

Discussion on: Extreme Makeover: Code Edition

Collapse
 
aspittel profile image
Ali Spittel

I like this article about comments.

Only at the point where the code cannot be made easier to understand should you begin to add comments.

Collapse
 
kip13 profile image
kip

If the code is abstract to the main idea, of course !

Sometimes you need comments but most of the time you need to think twice if is necessary.

From your shared post

Sometimes when I’m writing code, I think “I should comment this”

Right. The first and proper response to that feeling is to roll up your sleeves and refactor the code. After you’ve refactored, if you still feel a comment is necessary, then by all means add one. Never comment before you’ve attempted to refactor away the comment first.

Collapse
 
ben profile image
Ben Halpern
Thread Thread
 
kip13 profile image
kip • Edited

Good post, thanks for sharing Ben.

Maybe this can be an simple example:

(function() {
    // Is necessary apply the `bind` method
    // to set `this` in the right context
    const $ = document.querySelector.bind(document);

    // more code...
})();

This saves the time of going to the documentation or being confused, but it is not redundant, is the main idea that I'm trying to share, IMHO the comments are useful always in the correct way.

Thread Thread
 
ben profile image
Ben Halpern

I love React's dangerouslySetInnerHTML which replaces a lot of documentation and comments and forces the user to understand what's going on. If you don't know why it says "dangerous", you can look it up.

Much better than

//This is dangerous, read this post about XSS:
setInnerHTML

Because the comment would never get ported across all the use cases (obviously, given it's a library).

But most code doesn't live up to the scrutiny of library code and comments, used properly, are a perfectly reasonable part of the toolbelt.

Thread Thread
 
kip13 profile image
kip

Yes, yes and yes !

I have never used React but dangerouslySetInnerHTML is so clear !

Thread Thread
 
nickytonline profile image
Nick Taylor

Yeah, I've only ever used it once and it was to inject release notes into a component from an external HTML file. yolo.