code Archives - Complete, Concrete, Concise https://complete-concrete-concise.com/tag/code/ Practical Information Without The Bloat Fri, 22 Mar 2019 20:02:13 +0000 en-US hourly 1 https://wordpress.org/?v=6.9 Comments in HTML and CSS https://complete-concrete-concise.com/tutorials/webdev/front-end-basics/comments-in-html-and-css/ Mon, 11 Feb 2019 15:36:32 +0000 https://complete-concrete-concise.com/?p=3789 Comments help to document and explain your code to others and your future self.

The post Comments in HTML and CSS appeared first on Complete, Concrete, Concise.

]]>

An important part of coding is documenting your code with comments

Contents

  1. Introduction to Comments
  2. HTML Comments
  3. CSS Comments
  4. Guidelines for Writing Good Comments
  5. Final Words
  6. References

Introduction to Comments

In a perfect world, code would be self documenting and as you read it from top to bottom you would perfectly understand its structure and behaviour.

In the real world – except for trivial code examples (the kind you fit in a dozen lines or less and can keep in your head) – understanding any significant piece of code takes considerable effort.

Comments are textual information that are added to the code to help document the code. Comments do not affect the behaviour of the code in any way and are ignored when the code is processed. Comments are there to help humans understand the code easier – but only if they are useful and accurate.

HTML Comments

HTML comments begin with <!-- and end with -->. In between those characters, you can have almost any type of text string you like and it can span multiple lines.

The specification has a few rules regarding HTML comments:

  1. the text must not start with the string >,
  2. nor start with the string ->,
  3. nor contain the strings <!--, -->, or --!>, +
  4. nor end with the string <!-

Basically, as long as you don’t try to nest HTML comments inside HTML comments, you will be fine.

CSS Comments

CSS comments begin with /* and end with */. In between those characters you can have almost any types of text string you like and it can span multiple lines.

As with HTML comments, you cannot nest CSS comments, so the first */ will always end the comment:

Guidelines for Writing Good Comments

Comments are written for two types of audience:

  1. Your future self
  2. Others

Your future self (technically speaking) is somebody else because, 6 months or a year or 10 years in the future, you are unlikely to still be in the same frame of mind as when you wrote the code. So everything that was “obvious” when you were writing your code is no longer obvious.

Comments are written for two different purposes:

  1. Documenting (what you are doing)
  2. Clarifying (why you are doing it)

Comments should answer the questions: what and why. The how is answered by the code itself because that is the implementation.

Let’s comment the first HTML program we encountered in this tutorial series:

In general, you shouldn’t comment as extensively as I did in the example above – but for a tutorial it is fine.

When you are learning, it is a good idea to comment freely – explain what you are doing and why you are doing it. As your knowledge develops, you will find yourself documenting less and less.

Your comments should document why you are doing something. For example, you might have a requirement for a particular type of webpage, you could embed the webpage description as a comment:

Of course, this information could be in an external design document instead of the webpage.

The big problem is maintaining the code comments up to date. You have to be diligent to ensure that you update the comments when making changes to the code that don’t do what the comments say.

I recommend you comment freely as you learn to develop. Comment what you have learned:

Eventually, you will stop writing mundane comments.

You should avoid commenting what is obvious from reading the code because it adds nothing to the information:

But you can document specific requirements:1

One use of comments is to structure your code:

Unfortunately, your code won’t always cooperate to break down into such nice clear categories.

Final Words

  1. Comment your code freely.
  2. Don’t comment anything that is obvious.
  3. You can explain what you are doing.
  4. You can explain why you are doing something.
  5. Don’t explain how how you are doing something because that is the code itself.
  6. Keep your comments up to date (in general, you should avoid comments that could be rendered obsolete)

References

  1. HTML comments
  2. CSS comments

  1. Read more about Twitter’s brand requirements. Many organizations and companies have very specific rules regarding the use of colours or fonts or any other aspects that are associated with their brand.↩

The post Comments in HTML and CSS appeared first on Complete, Concrete, Concise.

]]>