Timeline for How to make a large codebase easier to understand
Current License: CC BY-SA 4.0
33 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jun 12, 2019 at 15:05 | history | edited | Robert Harvey | CC BY-SA 4.0 |
edited title
|
| Aug 21, 2015 at 4:22 | audit | First posts | |||
| Aug 21, 2015 at 4:23 | |||||
| Aug 14, 2015 at 15:39 | history | tweeted | twitter.com/#!/StackProgrammer/status/632214976493711360 | ||
| Aug 8, 2015 at 14:39 | answer | added | Sam Jones | timeline score: 0 | |
| Aug 6, 2015 at 18:15 | comment | added | user4459 | Are you documenting your requirements in SRS format or P-Spec format? That would be helpful too. | |
| Aug 4, 2015 at 15:33 | comment | added | Chris Cirefice | I just took over an Android app 4+ years in development that has basically no documentation. You know what would be nice right now? Documentation like yours. | |
| Aug 4, 2015 at 15:24 | comment | added | Anubian Noob | I love this. It includes a lot of the implicit understanding you have of the codebase, that's not written anywhere, and by writing it, you've done a huge favor for the next guy. | |
| Aug 3, 2015 at 16:02 | comment | added | rpax | @Telastyn On mondays I am Joe the Perfectionist. Fridays make me Disaster Bob | |
| Aug 3, 2015 at 9:02 | answer | added | Niall | timeline score: 6 | |
| Aug 2, 2015 at 20:21 | answer | added | gnasher729 | timeline score: 3 | |
| Aug 2, 2015 at 12:54 | history | protected | gnat | ||
| Aug 2, 2015 at 12:41 | comment | added | jwenting | that's nice to understand what a specific source file does, but it doesn't tell you anything about how all the different source files fit and work together. It's also imperative that it gets properly maintained, changed with the source file. And in my experience THAT is where such comments fall, they tend to not be properly maintained because there's "no time for it", things get changed rapidly to meet changing requirements or bugfixes that need to go out NOW and all that happens is a note somewhere "TODO update documentation" which then never gets done. | |
| Aug 2, 2015 at 11:25 | answer | added | akaltar | timeline score: -1 | |
| Aug 2, 2015 at 9:55 | answer | added | Low Flying Pelican | timeline score: 13 | |
| Aug 2, 2015 at 8:34 | comment | added | candied_orange | In Java you document for users of the code in the java doc. You document for the maintanence programmer inside the class / method. | |
| Aug 2, 2015 at 6:51 | answer | added | Cort Ammon | timeline score: 4 | |
| Aug 1, 2015 at 23:27 | comment | added | Michael Hampton | There's documentation for users of your class, and then there's documentation for maintainers of your class. As a user of the class, I don't really care about the workarounds you had to implement to make X talk to Y. But if I have to maintain your code, or even if I have to read it for some reason, (which almost amounts to the same thing) then I care a lot. | |
| Aug 1, 2015 at 16:52 | comment | added | mucaho | One thing to note: This has certainly many upsides, but once your design changes, you have to make sure to update this documentation too. I am not aware of any tool-support for changing documentation (unlike for code refactoring). | |
| Aug 1, 2015 at 15:48 | comment | added | Lightness Races in Orbit | @Telastyn: Yeah, maybe. Personally I'd write it in a standalone doc. But comment blocks at the top of source files isn't so bad. | |
| Aug 1, 2015 at 15:08 | comment | added | Telastyn | @LightnessRacesinOrbit - but not in code. There are better tools for doing that. | |
| Aug 1, 2015 at 15:01 | comment | added | Lightness Races in Orbit | @Telastyn: This has nothing to do with whether the code is readable or not (and I hope it is). Documenting design rationale is absolutely important. | |
| Aug 1, 2015 at 9:43 | comment | added | slebetman | @zxq9: Architecture/high-level docs have thankfully become a standard culture of github. So much so that I won't use a library with an incomplete README.md file. The github solution to rotting documentation is that inaccurate documentation generate a bug report | |
| Aug 1, 2015 at 9:26 | answer | added | meriton | timeline score: 38 | |
| Aug 1, 2015 at 8:58 | answer | added | DWalker | timeline score: 8 | |
| Aug 1, 2015 at 8:51 | comment | added | zxq9 | At a higher level at least, an out-of-code prose description of what a project does, how it works, and what tradeoffs have been made in the architecture is invaluable. This sort of a document is a must-read for a newcomer before they take a code tour. There is a lot of my-methodology-is-too-radical-for-docs-dude bullshit around the net, and while it is true that an initial arch doc and an evolving arch doc won't align, a prose description is necessary for anyone to quickly grasp a large, non-trivial codebase. Here is a (poor) example: zxq9.com/erlmud/html/001-002_architecture.html | |
| Aug 1, 2015 at 6:32 | comment | added | rwong | This is not to say the idea is not useful; it is that in real life good ideas that do not result in immediate benefits for its laborers tend to be neglected, and the out-of-date information might become unreliable over time, such that the readers of such notes need to treat it with some suspicion. | |
| Aug 1, 2015 at 5:17 | answer | added | Ilqar Rasulov | timeline score: -7 | |
| Aug 1, 2015 at 3:11 | comment | added | Telastyn | @jeffo - the problem is that taking the time to do this can happen once. The time to keep code readable happens over time. I've been at places with this sort of documentation, done when the project was young, or when Joe the Perfectionist was still on the team. It then got abandoned and the comments lingered on, no longer accurate. | |
| Aug 1, 2015 at 1:37 | comment | added | JeffO | @Telastyn - How many projects are willing to take the time to do this, but still write unreadable code? May not be causation, but I'll bet there is a good correlation. | |
| Aug 1, 2015 at 0:47 | review | Close votes | |||
| Aug 14, 2015 at 3:04 | |||||
| Aug 1, 2015 at 0:29 | comment | added | Telastyn | Hell no. If your code is unreadable, documentation won't help. | |
| Jul 31, 2015 at 22:42 | answer | added | Robert Harvey | timeline score: 143 | |
| Jul 31, 2015 at 22:33 | history | asked | Alex Spataru | CC BY-SA 3.0 |