1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
\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}
|
