diff options
Diffstat (limited to 'book/module2/documentation.tex')
| -rw-r--r-- | book/module2/documentation.tex | 64 |
1 files changed, 0 insertions, 64 deletions
diff --git a/book/module2/documentation.tex b/book/module2/documentation.tex deleted file mode 100644 index ebd9d87..0000000 --- a/book/module2/documentation.tex +++ /dev/null @@ -1,64 +0,0 @@ -\section{Documentation of your code}\label{documentation-of-your-code} - -Code documentation is essential for maintaining and scaling software -projects. Whether it's an open-source project or your own private code. -It ensures that you can understand, use, troubleshoot and build upon the -code in the future. - -\subsection{Keep Detailed and Accurate -Notes}\label{keep-detailed-and-accurate-notes} - -Just as a recipe requires clear instructions, your code should be -accompanied by comprehensive notes. Document your process thoroughly to -ensure that others (and future you) can follow along without confusion. - -When documenting a project, it's essential to include detailed notes -that capture not just what the code does, but how it was developed. This -includes recording libraries used, citing any external code snippets -along with their sources, and outlining the sequence of steps taken -throughout the coding process. Such comprehensive documentation enables -others---and your future self---to understand, recreate, and maintain -the project more effectively, reducing confusion and improving long-term -usability. - -\subsection{Explain Your Decisions}\label{explain-your-decisions} - -In programming, there are often several valid approaches to solving a -problem. When documenting your code, it's important to clarify why you -chose a particular method---especially if it deviates from common -practices. Anticipating potential questions and addressing them directly -in your documentation helps others follow your reasoning and builds -trust in your solution. \includegraphics{figures/rubberDuck.png} A -useful strategy for articulating these decisions is the ``rubber duck'' -technique---explaining your code as if you're teaching it to someone -else. Whether spoken aloud or written down, this practice helps you -clarify your logic and communicate the reasoning behind your choices, -providing valuable context for future collaborators or -reviewers.\hspace{0pt} - -\subsection{Include a README}\label{include-a-readme} - -A README file serves as the introduction to your project. It should be -placed in the top-level directory and provide essential -information.\hspace{0pt} A good readme file may include: - Project title -and description - Installation instructions - Usage examples - -Contribution guidelines (if applicable) - License information (if -applicable) - -This file acts as a roadmap for anyone interacting with your project. -\hspace{0pt} - -\subsection{In-line Comments}\label{in-line-comments} - -While external documentation is vital, in-code comments provide -immediate context. Use them to explain complex logic or important -sections within your code.\hspace{0pt}Here are some guidelines to -follow: Keep comments concise and relevant. Avoid stating the obvious; -focus on the ``why'' rather than the ``what.''. - -\subsection{Maintain and Update -Documentation}\label{maintain-and-update-documentation} - -Similarly to your code, the documentation should evolve alongside your -code. Regularly review and update it to reflect changes, ensuring -accuracy and relevance.\hspace{0pt} |
