[temporallobe]

I know this will get downvoted into oblivion on HN - but I just can’t resist. Another way to write unmaintainable code - write it the Ruby/Rails way! No comments, no flowerboxes, no docstrings! Your method and variable names ARE your documentation!

In all seriousness though, I have found that even with carefully and thoughtfully named variables, classes, methods, etc., code with no comments and no human-readable explanation is very difficult to maintain. I’ve been doing it for years and it never gets easier, especially with large code bases. Yes, the ROI for adding useful comments may seem low now, but it does pay off for the unlucky newb, intern, or junior engineer who’ll be stuck fixing that tricky bug or integrating that odd feature request in the future.

[igornadj]

Can you elaborate? What are the juniors stuck on? Usually if a junior doesn't understand something it means the naming/structure is not as clear as you think. One of my favourite things as a senior is having a junior peer review my code, the places they have questions is a great sign the change needs work.

[temporallobe]

I didn’t mean stuck “on”, I meant stuck “with”. I say this because juniors are often tasked with fixing the odd, seemingly easy bug, but if they don’t know the code base well, and especially if it’s not well documented, it could be a challenge, often requiring the seniors to work with them.