[parvenu74]

Seems like "yet another tool to try to offset the problem of requirements, code, and architectural decisions not being adequately documented for future staff to understand." Sometimes I wonder if software teams should add technical writers embed with developers, architects, QA, and BA assets to actually document All The Things and keep documentation up to date. Yes, that will mean re-writing documentations as people change their minds in response to business needs but it would provide an historical record that answers "How the hell did our systems end up looking like this?" which seems to plague every organization that hires programmers to write custom code. Sometimes it's hard to give the developers who wrote the code the benefit of the doubt that they made the wisest decision based on all known variables at the time. I'm certainly guilty of questioning the intelligence, breeding, motivations, etc of the programmer of an app I had to modify once... only to realize that I had written the code in question four years previously. Eventually I remembered why the feature had to be coded that way and wrote a 1200 word comment section explaining why the feature was written the way it was and how one should orient their state of mind to understand and edit the logic. And I further apologized for the clusterfuck of code that the feature was and left my personal email address in case a future programmer wanted to berate me for it. And three years later I did get an email from someone saying they had been laughing for ten minutes because they had gone from "WTF?" to gradual understanding as they read through my verbose description of why... ending with laughter that I was willing to take whatever vitriol they had left over via email so they could vent and get back to work. Whether that dev updated the comments to reflect their changes is something to which I have no answer.

[organsnyder]

For the past few weeks, I've been digging into a codebase that is legendary among my team for its complexity. While I have disagreements over some architectural choices, the biggest pain point has been the lack of documentation: when I look up the JIRA story referenced in the git commit, it's often a 4-pointer (the highest value we use before we break stories up) with no context. I found one story that had EIGHT pull requests linked to it, and all that was documented was "modify {entity}".

This code base is not even two years old, and I'm already concerned about its long-term viability. The colleagues that worked on it are extremely helpful, but details are fading from their memories over time. Its one saving grace is the fairly extensive test suite, so at least I have some degree of confidence that I won't be breaking things whenever I look at it the wrong way.

[parvenu74]

Perhaps a framework for minimal effective documentation would help. Requiring documentation that starts with "As a {role} I want to {verb}" might not be as effective as saying an application can be defined as a set of features, and each feature is described by it's list of acceptance criteria -- each of which map to one or more unit tests. In addition to all of this would be something in free-form prose from a business operations person describing why a feature needs to be added or modified. "Our competition is kicking our ass because they have feature X in their product and we don't -- we need to fix this." I'm not sure every feature should have something that looks like a mission statement but it would certainly elucidate the motivation for adding/modifying the feature in question.

[ShroudedNight]

> Sometimes I wonder if software teams should add technical writers...

I have been wondering the same thing fairly frequently of late. I see a few different potential benefits to something like this:

1) I communicate with relatively low friction face-to-face, but writing is like pulling teeth. Being able to outsource the formalization of knowledge would allow me to spend my time doing what I'm good at. I would hazard a guess that I am not alone in this matter.

2) There have been numerous times in the past when, despite my best efforts, some key subtlety of code that I had written was not communicated effectively until someone essentially comsumed my communications and regurgitated their own understanding of it. Having this process be the default would yield documentation that was a lot more effective at educating rather than simply being a reference to those that already know.

3) There is a surprising segment of developers that do not value clarity over volume, and most interactions with non-trivial quantities of their code result in having to engage in what is essentially a guided re-write. Having every long-term artifcat subject to a professional bringer-of-clarity would significantly reduce friction in the medium, allowing for much bolder and more effective trade-offs when reconciling a new requirement to an existing system.

4) Having well-archived, clear documentation would significantly increase the speed at which new members become effective, while also lowering the overhead imposed on existing team members.

[gm-conspiracy]

Also, this person could help with "time tracking".

[heartbreak]

I think in most cases "perfect" documentation that is always up to date, fully covers the software project, etc. would be overkill. Most of us aren't writing software for self-driving cars, rocket ships, and surgery suites. We're writing "spreadsheets in the cloud" where requirements change on every conference call, and documentation is JIT because that's all the client can afford.

Private Q&A like this from Stackoverflow would be perfect for my team. It would boost our institutional memory so that when questions are asked they're stored in SO, searchable, maintainable, etc. instead of stored in a Slack archive.

[dbingham]

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.

[zip1234]

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.

[zamber]

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.

[vgy7ujm]

So it was less than 100 lines of actual needed Perl code in that script? ;)

[zamber]

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.                   #
  #                                                                             #
  ###############################################################################

[nugator]

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.

[2trill2spill]

> 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.

[abhishekjha]

>provide an historical record that answers "How the hell did our systems end up looking like this?"

Version control?

[garrettgrimsley]

Version control only answers "what happened?" not "why did this happen?"

[pm215]

"Why" is what commit messages are for (and also comments); quality of commit message is worth checking in code review while the details are still fresh in everybody's minds...

[baq]

so i have to run blame just to figure out why something happened? i usually ask for explanations both in comments and commit messages.

[kamaal]

>>Sometimes I wonder if software teams should add technical writers

Part of CMM level 5 process was things like 'Knowledge teams' which did exactly that.

Agile eat CMM for lunch though.

[OpenDrapery]

What is the general opinion of CMM these days? I always associate it with UML diagrams for some reason. There was a time when the industry really wanted software to be fully specified. Seems like most people gave up on that dream, when agile came around and said "embrace change", along with the tenants.

But, alas, the pendulum swings. I think it's swinging back toward "I sure wish we didn't have to depend on finding skilled people, and our process was so bulletproof we could plug in any old schmuck and we can just continue to print money".

Damn, the business man is greedy.