Scale of Documentation

Started by
0 comments, last by Vangelis 20 years ago
I''m working within a small team of friends who are trying to put together a little game. I want to keep everyone on the same page, and not have anyone left in the dark so the implementation of the modules we create is quite important. I was wondering if it''s worth documenting every little last detail of the class (private variables etc.), or only the public interface (public functions that would use the private variables). The other programmers will not be doing much editing of the already created modules (or so we hope), so do they need to know about all the details of a particular system? Or should I create two documents, one being the "end-users" which documents the public interface, and another completely technical describing every last detail. --------------------- Ryan Bujnowicz [ vangelis ]
---------------------Ryan Bujnowicz[ vangelis ]
Advertisement
Code should be self-documenting. If it isn''t obvious to a competent programmer (who speaks your language) what a function is for, or why particular statements are in there, then it needs comments.

But that should be the exception rather than the rule.

I would normally say: Document public interfaces if it seems necessary.

Example: getName() might not need a documentation comment; but if it isn''t obvious what the name *IS* that it will get, it might.

countInventoryItems() might not need documentation, but if there is any ambiguity as to what an inventory item is, it may.

Document implementation where it is natural to do so within it, for example, if you write a function in pseudo-code (which is a good idea, generally speaking), leave the pseudo-code comments in.

Mark

This topic is closed to new replies.

Advertisement