Meine Damen und Herren, habe ich Ihre Aufmerksamkeit?

Mahlzeit,

Ja, das muss man ja nicht für jede Variable einzeln dokumentieren, es reicht aus das in einem Styleguide für den allgemeinen Fall festzuhalten.

Dann hast du noch nie für eine Firma wie T-Sytems gearbeitet (und auch andere, die ein eigenes Qualitätsmanagement für Dokumentationen haben. Auf 25 Projektteilnehmer kommen grad mal 5 Programmierer) ;)

Für T-Systems habe ich noch nicht gearbeitet und würde ich auch nicht wollen, wenn deren Workflow so unsinnige Dokumentation vorsieht. Jede Variable zu dokumentieren ist einfach Unsinn, dann kann ich auch direkt den Quelltext lesen. Eine gute Dokumentation behandelt verwendete Muster und logisch geschichte Schnittstellen-Dokumentation. Eine zeilenweise oder ausdrucksweise Dokumentation bietet gegenüber dem reinen Quelltext kaum einen Mehrwert, es macht nur unnötige Arbeit die Dokumentation mit dem Quelltext synchron zu halten. Feingranulare Dokumentation kann fallls nötig in Form von Quelltext-Kommentaren stattfinden, aber das ist unter keinen Umständen der Einstiegspunkt für Entwickler, die sich einen Überblick über die Architektur der Software verschaffen möchten. Um einen Entwickler das zu ermöglichen muss schon sehr viel gedankliche Abstraktion in die Niderschrift eingeflossen sein, da haben interne Variablen-Bezeichner nichts mehr verloren.

Um die Code-Qualität zu garantieren sind zudem Modul-Tests ein häufig verwendetes Werkzeug. Es ist doch viel beruhigender zu wissen, dass ein gewisses Modul das tut, was es soll, anstatt zu wissen, wie es das macht. Styleguides habe ich ja schon genannt, die lassen sich übrigens teilweise auch automatisiert validieren. Es gibt viele, viele weiteren Werkzeuge, um die Code-Qualität zu gewährleisten, speziell für JavaScript gibt es idiomatic.js auf GitHub, das öffentliche Repository dokumentiert solche Code-Quality-Tools. Mit einer breiten Palette aus diesem Werkzeugkasten ist man deutlich besser und effizienter aufgestellt als mit stupider und gedankenloser Quelltext-Dokumentation.