If you are asked to read and understand a software that spans 10000s of lines of code, it is impossible to do it. Even if you spend months, you may be able to fit some pieces but will not end up getting a hang of what the code does.
This is the real bane of software. In fact this is true even for some one who has had a long gap and end up staring at his own code.
This is true, no matter how much of annotation, commenting, documentation that is there.
Code commenting and documentation is only a small step in the direction of understanding one’s code. The reason is, a code is something that changes so drastically during its early phases. Almost all the parts of the code is volatile like a molten lava. Needs change, perceptions change, how you solve something change. It is hard to keep up the documentation or commenting in line with the code change and it will almost always be erroneous.
Coding a large software is like carrying a model in your head which is having several moving parts. It is like how Einstein would have carried his view of the universe and all the lingo of general relativity and associated visuals, albeit in a small way. No other person can understand it unless they get this model right. No matter how much of a documentation is out there.
Over time, if the product survives, portions of the code gets stabilized. If the design decisions, the perception of customer needs are reasonably accurate, the initial core of the code remains somewhat intact. This is really the time to ‘document’ the code. This is when the model in the head of the programmer can be laid out in diagrams and words and comments and algorithms to make sense to others who may enter to maintain or enhance it.
I would say the initial period of development of anything should be by a team which is sitting next to each other. Until it reaches the ‘inner core’ level of stability there is no need to document anything. Everyone simply codes. Everyone talks and listens to one another and grow the model in their heads.
Teams spread across require specs to be developed and integration etc. to be planned. These are like turning an already muddy water. If there is a choice, never have your initial development spread across teams. This is because, unless two brains are in synch in terms of the language spoken, visualizing the model there is always a gap to be filled up and time to be wasted and mistakes to be made and frustrations to be built up. And two brains to be in synch is not a question of skill, but a question of attitude. Hard to get.
Even if there are documentation after reaching the stability, it is nothing like having the original team around. If you happen to lose the key members, ensure their video lectures are captured that gives the ‘model’ that was visualized, key algorithms used, key decisions, assumptions made all along. This can help the developers to latch on to the context of looking at the code.
This is the real bane of software. In fact this is true even for some one who has had a long gap and end up staring at his own code.
This is true, no matter how much of annotation, commenting, documentation that is there.
Code commenting and documentation is only a small step in the direction of understanding one’s code. The reason is, a code is something that changes so drastically during its early phases. Almost all the parts of the code is volatile like a molten lava. Needs change, perceptions change, how you solve something change. It is hard to keep up the documentation or commenting in line with the code change and it will almost always be erroneous.
Coding a large software is like carrying a model in your head which is having several moving parts. It is like how Einstein would have carried his view of the universe and all the lingo of general relativity and associated visuals, albeit in a small way. No other person can understand it unless they get this model right. No matter how much of a documentation is out there.
Over time, if the product survives, portions of the code gets stabilized. If the design decisions, the perception of customer needs are reasonably accurate, the initial core of the code remains somewhat intact. This is really the time to ‘document’ the code. This is when the model in the head of the programmer can be laid out in diagrams and words and comments and algorithms to make sense to others who may enter to maintain or enhance it.
I would say the initial period of development of anything should be by a team which is sitting next to each other. Until it reaches the ‘inner core’ level of stability there is no need to document anything. Everyone simply codes. Everyone talks and listens to one another and grow the model in their heads.
Teams spread across require specs to be developed and integration etc. to be planned. These are like turning an already muddy water. If there is a choice, never have your initial development spread across teams. This is because, unless two brains are in synch in terms of the language spoken, visualizing the model there is always a gap to be filled up and time to be wasted and mistakes to be made and frustrations to be built up. And two brains to be in synch is not a question of skill, but a question of attitude. Hard to get.
Even if there are documentation after reaching the stability, it is nothing like having the original team around. If you happen to lose the key members, ensure their video lectures are captured that gives the ‘model’ that was visualized, key algorithms used, key decisions, assumptions made all along. This can help the developers to latch on to the context of looking at the code.
