How do you document game code for easy modification?

1 Choose a style guide

A style guide is a set of rules and conventions for writing and formatting your code. It helps you to keep your code consistent, readable, and organized. A style guide can include aspects such as naming, indentation, comments, spacing, brackets, and more. You can follow an existing style guide, such as the Google C++ Style Guide or the PEP 8 Style Guide for Python, or create your own based on your preferences and needs. The important thing is to stick to your chosen style guide throughout your project and document it in a separate file or wiki.

2 Use comments wisely

Comments are lines of text that explain the purpose, logic, or functionality of your code. Although they are ignored by the compiler or interpreter, they are essential for human readers. Comments can help you and other developers to understand, debug, and modify your code. However, if not updated or deleted when the code changes, comments can become outdated, misleading, or redundant. Therefore, it’s important to use comments wisely and follow some best practices. For example, comments should describe what the code does instead of how it does it; they should be concise, accurate, and relevant; consistent and easy to find; and updated or deleted when the code changes. To achieve this, use a consistent style and format for your comments (e.g., // for single-line comments and /* */ for multi-line comments in C++, or # for single-line comments and """ """ for multi-line comments in Python). Additionally, use keywords or tags to mark important or special comments (e.g., TODO, FIXME, or HACK).

3 Use documentation tools

Documentation tools are software applications that help you to generate, maintain, and share documentation for your code. They can extract information from your code, such as comments, variables, functions, classes, and modules, and create structured and formatted documentation files. Examples of documentation tools include Doxygen for C++, Sphinx for Python, or Javadoc for Java. Documentation tools can offer several advantages. For instance, they can ensure that your documentation is consistent and comprehensive, with cross-references, links, tables of contents, and indexes. Additionally, they can enable you to add features to your documentation like syntax highlighting or code examples. Furthermore, they can output your documentation in different formats and platforms such as web pages or PDF files. Finally, they offer the ability to publish or collaborate on your documentation using hosting services or version control systems.

4 Use code snippets and templates

Code snippets and templates are reusable pieces of code that can be inserted, modified, or extended in your project, saving time and effort, avoiding repetition and errors, and maintaining consistency and quality. These can range from common or frequently used code, such as functions, classes, loops, or conditions, to specific or customized code, like game mechanics, algorithms, or effects. You can create your own code snippets and templates, or use existing ones from online repositories or libraries. To ensure smooth usage of code snippets and templates, it is important to organize and label them with a clear and descriptive name. Additionally, placeholders and variables should be used to mark the parts of the code that need to be filled in or changed according to the project. Finally, it is recommended to use a code editor or an IDE that allows for creating, managing, and inserting code snippets and templates into the project. Examples include Visual Studio Code, Sublime Text, or Unity.

5 Use version control systems

Version control systems are software applications that enable you to track, manage, and collaborate on changes to your code. They document the history, progress, and status of your code, and enable you to compare, merge, or revert changes. You can also create and switch between different versions or branches of your code, and test or experiment with new features or modifications without affecting the main version or branch. Examples of version control systems include Git, Subversion, and Mercurial. The benefits of using version control systems are numerous: they keep a backup and log of your code; detect and highlight conflicts or errors when changes are made; and allow you to share and synchronize code with other developers working on the same project. Additionally, they provide features such as comments, messages, and pull requests to facilitate communication and coordination between developers.

6 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?