4 ms·
Self-documenting code is all code. The only thing that speaks to what a piece of code does is the code. Comments aren’t syntax, so they don’t help you there. I’
by Olreich 6y ago
Self-documenting code is all code. The only thing that speaks to what a piece of code does is the code. Comments aren’t syntax, so they don’t help you there. I’ve never seen a codebase that does a good job of documenting the system architecture, expected usage patterns, and why the code is built the way it is. And I don’t know that having all that be inline to the code would be helpful anyway.
I find it far less error prone to just read the code and determine its purpose and allowable modifications from that. I am thinking about what a citation or footnote system might look like for code now though. That has the potential to provide context on-demand without needing to separate out all the pieces of the code into little silos that are hard to piece together.
- faizshah 6y agoSelf-documenting code is a total myth. Instead of the author documenting what a piece of code does, why it does it that way and how to use it everyone who works on that code has to spend hours looking through the commit history, merge requests, design docs, wiki history, asking around etc piecing together the history and conversations around the code. Sometimes these artifacts don’t exist so then you have to go do the same research the author did to write the code just to figure out why the code exists... Note that none of those activities are reading the code itself because you can do that in both scenarios.