Advertisement Jump to content


This topic is now archived and is closed to further replies.


Scale of Documentation

This topic is 5396 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

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 ]

Share this post

Link to post
Share on other sites
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.


Share this post

Link to post
Share on other sites

  • Advertisement

Important Information

By using, you agree to our community Guidelines, Terms of Use, and Privacy Policy. is your game development community. Create an account for your GameDev Portfolio and participate in the largest developer community in the games industry.

Sign me up!