This page is a work in progress.You can help improve it. →

Missing Document Title

theme: Next, 1

Documenting what we do

Hopefully our code is understandable only from reading what is there. We often, however, need to describe the process our code is following or require additional details about how our code works.

Just as with using good variable names, clarity of code comments help us. Remember that code is written once but read many times.

For this we can use comments in our code.


Commenting code in C#

// This is the name of our ship
var shipName = "Heart of Gold";
// We need to know how many characters there are in order to center the text on the screen.
var characterCount = shipName.Length;
/*
Build a Turboencabulator
The original machine had a base plate of pre-famulated amulite
surmounted by a malleable logarithmic casing in such a way that
the two spurving bearings were in a direct line with the panametric
fan. The latter consisted simply of six hydrocoptic marzlevanes, so
fitted to the ambifacient lunar waneshaft that side fumbling was
effectively prevented.
See: https://www.youtube.com/watch?v=Ac7G7xOG2Ag
See: https://en.wikipedia.org/wiki/Turboencabulator
*/

Editor support

Nearly every editor has support for adding and removing comments for both single lines of text as well as blocks.

In Visual Studio Code you can start a comment with the key Control / (or Command / on Mac) on any line.

This will start a new comment and you can type your text. If you press enter the cursor will make a new comment line.

You can toggle comments by highlighting the lines and pressing the commenting key combination.


[fit] Thoughts on commenting out code

As you write code you'll be tempted to "comment out" code. That is, take one or more lines of code and place them inside a comment.

This is natural and often done during development. We'd like you to adhere by one guideline:

Don't commit commented out code to your git repository

^ The idea here is that commenting out code should be a development-time activity. Never publish/share/commit files that have commented out code.


© 2017 - 2021; Built with ♥ in St. Petersburg, Florida.