Pushing the need for clear documentation is a battle I find myself frequently fighting. Many devs just aren't sure how to prioritize it or write it, and even worse, many seem to have absorbed the idea that code should be self documenting and that comments are a code smell.
Whoever is responsible for the idea that comments are code smell deserves to receive all future vitriolic emails from anyone who ever stumbles into a complex nest of undocumented code and has to figure out what the hell they're looking at.
Whoever thinks comments are a code smell has probably stumbled into a nest of documented code where the documentation was out of date and didn't refer to the latest code in question, causing intense confusion. Comments can certainly be helpful but there is nothing to guarantee that they will be up to date or even useful.
Indeed. Had to port a 2k perl script with gigantic comment blocks written in German. Eventually I recreated the intended functionality with ~150 lines of JS after painfully google translating everything. JIRA references would probably be lost completely by the time I worked on it.
More around 800 of sloc. At least I haven't had to preserve bugs. There were also red herrings in the comments, leftovers as the script was tweaked to fit business requirements. Imagine blocks like this spat around randomly between code blocks...
###############################################################################
# #
# DAS IST CODE #
# #
###############################################################################
# #
# Das macht Dinge. Ja, ich habe diesen Übersetzer eingegeben, nur um etwas #
# einfügen zu können. Hoffentlich ist dies nach einer doppelten Übersetzung #
# noch lesbar. Wenn nicht, dann fick es einfach. Nett, es geht gut zurück. #
# #
# Natürlich wurde Interpunktion und Rechtschreibung gebrochen. Es war um das #
# Jahr 11, als der Übersetzer nicht über die gesamte Politur der künstlichen #
# Intelligenz verfügte, so dass eins von acht Wörtern nicht übersetzt wurde. #
# Zum Glück funktionierte es sogar mit Code, obwohl es nicht zu kompliziert #
# war. Andererseits sind Deutsche ziemlich zurückhaltend (oder waren, als #
# diese besondere Monstrosität gemacht wurde), um Englisch zu lernen, so dass #
# selbst Variablen in der Muttersprache sein mussten. Ich verließ das #
# Unternehmen rund 3 Monate, weil ich eine Legacy Monstrocity (es war nur ein #
# gehacktes Addon-Skript, das von einem Plugin-System in einem #
# Unternehmens-CMS lief) reparierte, war nicht meine Sache. #
# #
###############################################################################
Sorry to say that I'm one of those guys.
I never comment code that is straightforward and easy to understand if I succeed with naming classes, methods and variables right.
If I need to solve something in an illogical way due to other requirements/bugs that are out of my control I comment it.
I have read to many comments stating the obvious or that are just plain wrong.
No comments are better than comments with errors. The code is the only true fact.
> Sorry to say that I'm one of those guys. I never comment code that is straightforward and easy to understand if I succeed with naming classes, methods and variables right. If I need to solve something in an illogical way due to other requirements/bugs that are out of my control I comment it.
I think that's fine. I only comment code that is not obvious, breaks common idioms used in the code base or stuff that seems stupid but is actually needed because of legacy code or systems.
Whoever is responsible for the idea that comments are code smell deserves to receive all future vitriolic emails from anyone who ever stumbles into a complex nest of undocumented code and has to figure out what the hell they're looking at.