Dylan: link to single-line and multi-line pages specifically instead of generic C-style comment page

2025-08-13T08:02:32Z

link to single-line and multi-line pages specifically instead of generic C-style comment page

← Older revision		Revision as of 08:02, 13 August 2025
Line 19:		Line 19:
	* Document the changes to code: use a [[changelog]] for this!		* Document the changes to code: use a [[changelog]] for this!

	== Example of a ~~single-line~~ [[C-style comment]] ==		== Example of a [[C-style single line comment]] ==
	<syntaxhighlight lang="c">		<syntaxhighlight lang="c">
	// this is a full-line C-style comment		// this is a full-line C-style comment
Line 25:		Line 25:
	</syntaxhighlight>		</syntaxhighlight>

	== Example of a ~~multi-line~~ [[C-style comment]] ==		== Example of a [[C-style multi line comment]] ==
	<syntaxhighlight lang="c">		<syntaxhighlight lang="c">
	/*		/*

Dylan: Comment: create

2025-08-08T22:05:49Z

Comment: create

New page

Comments are the way programmers explain parts of their code.

They act as guides to future maintainers as to how the [[codebase]] is [[Code structure|structured]].

== What comments should do ==
Comments are very useful when:

* You have a complicated piece of code and its function can be explained simply in a comment (often though, it makes more sense to create a function for this).
* You've found that the current implementation is [[Optimization|faster]], and want to explain that to future [[Code maintainer|maintainers]]
* Credit code from other sources
* Provide links to further reading on a concept
* Use [[doc comments]] for documenting a [[function]], struct [[field]], etc.

== What comments should NOT do ==

* Explain ''what'' the code is doing - e.g. redundant comments explaining why if <code>age < 18</code> checks <code>if age is less than 18</code>.
* Explaining an [[if statement]], [[switch statement]] or other [[condition]] - usually, this indicates you should create a [[constant]] for any [[Magic number|magic numbers]] in your [[condition]], or [[Extraction|extract]] out parts of your [[condition]] into separate ([[boolean]]) [[Variable|variables]].
* [[Commenting out]] code: this is ''ok'' in your <code>dev</code> [[Version control branch|branch]], but should '''never''' be in [[production]].
* Document the changes to code: use a [[changelog]] for this!

== Example of a single-line [[C-style comment]] ==
<syntaxhighlight lang="c">
// this is a full-line C-style comment
int a = 5; // you can also place them at the end of a statement
</syntaxhighlight>

== Example of a multi-line [[C-style comment]] ==
<syntaxhighlight lang="c">
/*
This is a multi-line comment
They start with a / then a * ...
... and end with a * then a /
*/

/* it's often convention to start each new line in
* a multi-line comment with an asterisk (*) to
* maintain formatting. */
</syntaxhighlight>

Comment - Revision history

Dylan: link to single-line and multi-line pages specifically instead of generic C-style comment page

Dylan: Comment: create