Jump to content
  • Advertisement

Archived

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

Vangelis

Scale of Documentation

This topic is 5240 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
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

Share this post


Link to post
Share on other sites

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!