>>So, as a conclusion, we can see that even for such a simple function >>like getChild there is a lot of room for misinterpretation. I >>completly agree to Antonio that there should be documentation for all >>functions. The documentation of the whole project currently is a >>complete mess, and it is hard to believe that the core developers (as >>we read in the last eMails) do not feel able to document their own >>code, something which is matter of course at least for me. >> >> >> >To a large extend it's a matter of when, and efficiency. If you document >before the API is stable, your time is wasted. If you do it too late, it >probably won't happen. In professional projects documentation takes >about the same time as coding, and that seems realistic to me. So >documenting everything halves development speed. I don't think you as >experienced users would be happy with that. New users would benefit, but >old ones would suffer. So far we've tried to keep the old ones happy, >but that came at the cost of not getting new ones quickly. Maybe it's >time to change that. > >Besides, developers don't like pain either, and writing documentation >definitely counts as painful. ;) > > I think this is a bit of a cop out. It makes it easier to justify not writing documentation, but that doesn't make it true.
How hard is it really to document a member variable when it is added or document a new method when it is created. The developer is already adding it, so they know what it does. It only takes about 30 seconds at the most to write a one or two sentence description of the thing. Documenting method behavior is a little more difficult, but once again when a developer is writing a piece of code they are already doing this in their head. They are thinking, what will this code do, what are the inputs and how will it work. Once again I would say that it doesn't take more then a minute to write this down for most methods. For most new classes that I write and try to fully document I would say that if the class takes 2-3 hours to write and test, then documenting it probably takes about 10 minutes of that time at the most. I would agree that writing large user guides and things like that can be painful. It is also painful to go through previously undocumented code and try to document it. But I don't think it is difficult at all to add brief comments to the code while writing it and to update those comments when changes are made to the code. The real painful thing is for a user when they have to try to figure out what a piece of code is supposed to do by reading the code everytime and similarly when a developer needs to fix or extend something and first they have to spend a good deal of time reading and understanding the code that doesn't have any comments. -Allen ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
