[mapguide-internals] Improving the Code Base/ General Approach to
Commenting Code / Inline Documentation as a community effort???
uvwild at gmail.com
Wed Mar 18 22:08:46 EDT 2009
in order to make sense out of the server source code (which contains
large amounts of duplicate code) I had to comment most methods
participating in the call sequences needed for my patch.
It was quite an effort to understand the code enough to be able to
comment the method functionality.
It would be a waste to throw this away.
As I do not have commit rights I was wondering about the process to
merge my patches (including the comments) back into the code base.
I think there was no build server with a continous build system and
embedded testbed which would make this fairly hazzle free.
Is there a peer review process in place or how is this handled?
INLINE DOCUMENTATION & REFACTORING
I believe reading the C++ code is not a very useful way to communicate
functional details so we should not underestimate
the value of inline documentation in the source code in particular in an
open source project. (see some of the included OEM sources)
Refactoring and method extraction would be another way to make the code
more readable but this is admittedly more complex and hard to implement
without an automated build and test system.
I believe however thats its a good investment into such a large code
base as it improves maintainabilty a lot as copy paste tends to
introduce errors after code changes in the copied parts.
In a previous project I worked at a large C++ application and understand
the missing time and/or reluctance
of most developers to write external documentation which leaves the code
base as the only means of communicating important details.
I have been hired to set up an automated doxygen based documentation
system running daily off the repository to improve coding efficiency.
This was the easy part, the hard part is to get the documentation into
the code base by the developers.
*This is a communal effort.
(I hope we are past the times when "Real Programmers don't need
comments-- the code is obvious." )
HOW TO IMPROVE INLINE DOCUMENTATION
Do we all agree how important it is for such a project to make it as
easy as possible to write inline documentation into the code base?
I believe the completeness of inline documentation is a major indicator
for OS project maturity and therefore the ease of adding comments
is a major factor in helping the community to improve it.
The external API is documented nicely but below that there is a lot
This is wasting a lot of time and results in more frustration than
necessary when working with this code base.
Slowing down the learning curve has a detrimental effect on the overall
advances of the project.
So we could think about a way to have different stages of commit rights
as in the early phase we are more keen on writing the comments
than later when we have commit rights and already understand whats going
1) additional level of commit right which only allows comment lines to
2) secondary repository for the comments with an automated merging process
Please comment :)
More information about the mapguide-internals