Badly designed systems aside, for most systems that currently exist or have existed in the past, there is little or no documentation that is worthy of existing. Most comments in code and the associated documentation in manuals fails to provide the reasoning as to why the code exists, why it is written that way, what underlying assumptions have been made, etc, etc, etc.
I am going through a process at the moment of documenting all of my local codebase. It will, in turn, be turned into a literate programming base. The problem I am finding is understanding all of the assumptions that underlay the original code. Why was it written this way or that, what is it trying to do, is the code actually doing what it is supposed to do?
There are, at present, some questions that I am having difficulty answering and this is my code. How much more difficult is it for someone to come in and look at a historical piece of code and follow what the original authors and designers were trying to achieve and what were the changes that have been made over time trying to achieve.
Documentation at the level we need to be able to adequately maintain any code base is just not done - it is very hard to do and to do so in a way that will help future people manage and maintain that codebase. On of my projects involves restructuring the code base. However, I need to understand the history of that codebase and that means talking with those people who are still living who knew the original authors and give an oral insight as to why things have been done the way they are. This oral history has to be written down and the codebase documented with it. When that information is in place, why the code is written the way and how we can now rewrite that code to be more effective is now achievable.
If we then put on top of missing history and documentation all of the bad designs, well, we are then facing even bigger problems. Then we put on top of that all the egos and politics involved, we get an even bigger mess.
So just reading up more doesn't actually help, because that which is needed was never written in the first place.
I meant documentation on whatever tools and libraries project uses. Specifically, a lot of lines that do nothing are 95% result of frameworks integration.
You should not need to look at those particular lines that much.
I agree that the other issues you described here make work on large long running projects harder. It is challenge and somethings fight for every inch. Which is why I am increasingly sick of people who can't do it kicking those who can and kicking tools that make it possible (I have better chance to figure out the system with oral history only you just described then in javascript or python. Not easy, but tools make it less hard.)
I am going through a process at the moment of documenting all of my local codebase. It will, in turn, be turned into a literate programming base. The problem I am finding is understanding all of the assumptions that underlay the original code. Why was it written this way or that, what is it trying to do, is the code actually doing what it is supposed to do?
There are, at present, some questions that I am having difficulty answering and this is my code. How much more difficult is it for someone to come in and look at a historical piece of code and follow what the original authors and designers were trying to achieve and what were the changes that have been made over time trying to achieve.
Documentation at the level we need to be able to adequately maintain any code base is just not done - it is very hard to do and to do so in a way that will help future people manage and maintain that codebase. On of my projects involves restructuring the code base. However, I need to understand the history of that codebase and that means talking with those people who are still living who knew the original authors and give an oral insight as to why things have been done the way they are. This oral history has to be written down and the codebase documented with it. When that information is in place, why the code is written the way and how we can now rewrite that code to be more effective is now achievable.
If we then put on top of missing history and documentation all of the bad designs, well, we are then facing even bigger problems. Then we put on top of that all the egos and politics involved, we get an even bigger mess.
So just reading up more doesn't actually help, because that which is needed was never written in the first place.