Start-up I'm working for as a front-end dev is pretty nice. I have good hardware, free coffee and my coworkers are all decent people. My boss is chill, and I have flexible work hours.

There is this one policy for writing code, however. And I simply cannot understand it, nor can I ignore it because of code reviews: no comments in production code.

I mean, what? Why? Comments are nice, and they make life easier for the future maintainers. At least let me put a small two-liner explaining why I did stuff this or that way. But no, I only get to explain it verbally (once) to the person reviewing my PR. Why, man?

  • 11
    There's this belief that comments are just noise and code should be easily deciphered at all times, regardless of what it is doing.

    I share a similar brief, code should be kept simple at all times, but when it's not and it's not self explanatory or it does things that really don't make sense to anyone but you and god, you write a comment in explaining it.
  • 3
    What front-end type stuff? Like html, css, js?

    Because minifying that will also remove any comments. And if you don't minify it: why?
  • 3
    @fuckwit should've explained it better, I think. Production here means what's being merged into master.
    And yes, it gets minifed and chunked (SPA) anyway, so comments are removed indeed
  • 1
    @C0D4 precisely, I strive to keep my code as simple as possible but sometimes it just can't be groked by reading, and in these situations I'd like to leave one or two lines commenting the logic or reason behind what I did
  • 2
    @Avyiel ah ok. Well then this policy is fking stupid. Yes code should be easy enough to not need a comment to explain it. But that sometimes simply isn't possible.
  • 6
    Code can only tell WHAT is being done, but not WHY. That needs comments, both so that a future dev doesn't screw it up because he doesn't understand the background, and for debugging in case the underlying reasoning was already buggy.
  • 1
    Comments can be a code smell.

    If you're writing a comment to describe what some code does, you are usually better off extracting that code into a method with a descriptive name. So, rather than having a block of code that reads a Markdown file, create a method called readMarkdown(). Or possibly extract it to a dedicated class.

    For frontend, work, it would be better to break up your UI with partials of some kind with a descriptive name. Or use a component-based library like Vue or React - that way all components can have suitable descriptive names.

    Cases where leaving a comment is the best way are actually very rare. That said, it's not worth agonizing over every last detail to remove comments as business concerns usually come first. Leaving a comment is acceptable, but should be a last resort.
  • 1
    I'm assuming you use something like webpack... Set it up to remove comments when building the prod version...
  • 0
    Maybe a shitty move as well, but: when the person reviewing it asks a question I would say that they shouldn't need any explanation since there are no comments allowed and you wrote it to readable
Add Comment