On 13 Dec 1999 18:28:14 +0100, Lars Gullik Bj°nnes wrote:
>
>| 1) In open source with a large number of rapidly changing contributors
>| comments are crucial to attract new collaborators and to assure project
>| survival when core contributors change. I think everybody knows
>| examples of failures.
>
>The largest problem with contributors or larger pieces are when they
>leave the project, and that code written by part time contributors
>often is very convoluted. Witht that I mean that code often is overly
>complex and insted of doing the coding strait forward it is overly
>complex.
If you write down some keywords about (or paint) your design, it
automagically becomes lean and straightforward. An example: A friend of
mine, as a programmer only an amteur like me, converted from closed
source to open source fanatic (now he does lectures about open source).
The reason was, the opening up made him comment his code. After doing
this, he became aware of formerly hidden bugs and how to simplify the
design.
>| there you should find the actual design documents. And doc++ is a good
>| thing to distill them.
>
>One thing that is a lot beter than comments is code written in an
>obvilous way, easy to understand.
There is actually a close relationship, IMHO.
>
>Ad. problems using cvs. You are allowed to ask how to use it.
>When I am working on something that I don't want to commit right away
>I just make the changes to the checked out sources, when someone else
>commits to the repository I just do an update, in 90% of the cases the
>merge is done with out complict and the conflicts that happens is
>usually very easy to solve.
>(and then you make the patch)
Yes, but I expect myself to try out the doc's etc. and to search for
some kind of tutorial, first. (This is to say, it might take some time,
'frozen' versions are therefore handy.)
>| /*** xy.C: For usage and design info please refer to xy.h. Please add
>| here only comments describing the specific implementation. Those
>| comments should ease maintenance and bug tracing. So please be careful.
>| Please add a test of your implementation as a comment at the end of
>| this module.
>| **/
>|
>
>This is only true if the comments are correct, you always have to check
>the sources anyway to see what the code really does.
If the comments are buggy the code... (see above ;-)
Greets,
Arnd
