Click here to Skip to main content
15,504,424 members

Welcome to the Lounge

   

For discussing anything related to a software developer's life but is not for programming questions. Got a programming question?

The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.

 
GeneralRe: Importance of Documentation Pin
Mircea Neacsu21-May-22 17:37
mvaMircea Neacsu21-May-22 17:37 
AnswerRe: Importance of Documentation Pin
Jacquers21-May-22 20:27
Jacquers21-May-22 20:27 
AnswerRe: Importance of Documentation Pin
RickZeeland21-May-22 23:32
mveRickZeeland21-May-22 23:32 
AnswerRe: Importance of Documentation Pin
Daniel Pfeffer22-May-22 1:04
professionalDaniel Pfeffer22-May-22 1:04 
AnswerRe: Importance of Documentation Pin
Sander Rossel22-May-22 3:22
professionalSander Rossel22-May-22 3:22 
GeneralRe: Importance of Documentation Pin
Mircea Neacsu23-May-22 10:03
mvaMircea Neacsu23-May-22 10:03 
GeneralRe: Importance of Documentation Pin
Sander Rossel24-May-22 1:47
professionalSander Rossel24-May-22 1:47 
AnswerRe: Importance of Documentation Pin
trønderen22-May-22 7:19
trønderen22-May-22 7:19 
I have been considering two alternatives for activities when I retire: Either, I could clean up messy, amateurish Wikipedia articles (maybe even add information, if the article is within my field of expertise. I don't see any possibility of running out of Wikipedia articles that need a cleanup.

Or, I could start working through open source projects, not contributing a single line of code, but adding documentation, from the very top level down to the individual methods, data exchange paths, data structures etc. Or, the intention would be to make neither code extensions or corrections, but I know very well from my documenting my own code (and partially that of others), that it serves perfectly well as rubberducking. When you have to give others a clear and concise description, you discover lots of things that passes by as long as you rush on to implement that new exciting functionality.

I guess that I will stick to Wikipedia. Revealing a messy architecture, inconsistent data structure designs, lack of thread protection where there should be, etc. in a clear and concise manner is bound to lead to a lot of people being upset for me picking on their code. I think that lots of programmers (both of closed and open source code!) fear a view from the outside on their program design. In code reviews, they are used to others reading their conditional statements and loops; that part is OK. But when a system has grown "organically" for five years into a terrible mess of pieces from the method level and upwards, it is rarely subject to a code review. And that is where the problems usually are found. And fixing them requires far more effort than fixes on the code level. No one wants to be told that their architecture and module design have deteriorated into a can of worms.

Well, it rarely is that bad, but most code bases that I have been in touch with have had so many deviations from what was once the original architecture that it negatively affects both reading and maintaining the code. Practically always, I hear "Yes, we know, but ... We hope to get around to clean it up ..." They would not want to have that in writing. They want to pretend that they have gotten that round tuit, even though it isn't the case.

I guess fixing up Wikipedia articles will make fewer people upset.
AnswerRe: Importance of Documentation Pin
PhilipOakley22-May-22 23:36
professionalPhilipOakley22-May-22 23:36 
AnswerRe: Importance of Documentation Pin
Cpichols23-May-22 3:20
Cpichols23-May-22 3:20 
GeneralRe: Importance of Documentation Pin
MarkTJohnson23-May-22 3:52
professionalMarkTJohnson23-May-22 3:52 
GeneralRe: Importance of Documentation Pin
Cpichols23-May-22 4:03
Cpichols23-May-22 4:03 
AnswerRe: Importance of Documentation Pin
RussellT23-May-22 4:03
professionalRussellT23-May-22 4:03 
AnswerRe: Importance of Documentation Pin
Matt Bond23-May-22 6:28
Matt Bond23-May-22 6:28 
AnswerRe: Importance of Documentation Pin
NightPen23-May-22 6:43
NightPen23-May-22 6:43 
GeneralRe: Importance of Documentation Pin
RussellT23-May-22 12:33
professionalRussellT23-May-22 12:33 
GeneralRe: Importance of Documentation Pin
NightPen23-May-22 16:09
NightPen23-May-22 16:09 
AnswerRe: Importance of Documentation Pin
pmauriks23-May-22 19:24
pmauriks23-May-22 19:24 
GeneralHave a good funky weekend ;) Pin
0x01AA21-May-22 9:24
professional0x01AA21-May-22 9:24 
GeneralRe: Have a good funky weekend ;) Pin
Sander Rossel22-May-22 3:49
professionalSander Rossel22-May-22 3:49 
GeneralThe world's leading expert on European wasps walks into a record shop. Pin
OriginalGriff21-May-22 9:16
mveOriginalGriff21-May-22 9:16 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
Mike Hankey21-May-22 9:25
professionalMike Hankey21-May-22 9:25 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
Marc Clifton21-May-22 9:55
mvaMarc Clifton21-May-22 9:55 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
Mike Hankey21-May-22 10:03
professionalMike Hankey21-May-22 10:03 
GeneralRe: The world's leading expert on European wasps walks into a record shop. Pin
OriginalGriff21-May-22 11:17
mveOriginalGriff21-May-22 11:17 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.


Straw Poll

How would you describe your current job?
Fighting dragons everyday or clicking the same boxes on the same forms, day after day?
  Results   406 votes