sec-comment.ptx

<?xml version="1.0" encoding="UTF-8"?>

<!--*****************************************
This is part of Basic Programming
Copyright (C) 2024
Phạm Công Vinh
See the file COPYING for copying conditions.
******************************************-->

<section xml:id="sec-comment" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Comments</title>

  <objectives>
    <ul>
      <li>Learn to recognize and use <term>comments</term> in code.</li>
    </ul>
  </objectives>
  
  <p>
    When coding, sometimes you want to write <term>plain text</term> instead of code. It can be notes, explanations for algorithms, or your stream of thoughts at that moment, <etc /> As the code expands and gets more complicated, these <q>comments</q> provide you with sufficient context.
  </p>

  <definition xml:id="def-comment">
    <idx><h>Definitions</h><h>of comments</h></idx>
    <statement>
      <p>
        <term>Comments</term> are pieces of plain text that will not be executed.
      </p>
      <p>
        To write a comment in Python, use the number sign (hash) <c>#</c>. What follows it (on the same line) will be regarded as plain text by the compiler.
      </p>
    </statement>
  </definition>

  <aside>
    <title>Topic(s) you might be interested in:</title>
    <p>
      <ul>
        <li>
          <p>
            <idx><h>Links</h><h>different comment syntax</h></idx>
            <url href="https://www.google.com/search?q=comments+in+different+programming+language" visual="google.com/search?q=comments+in+different+programming+language">"comments in different programming languages"</url>
          </p>
        </li>
        <li>
          <p>
            <idx><h>Links</h><h>multiline comments</h></idx>
            <url href="https://www.google.com/search?q=multiline+comments" visual="google.com/search?q=multiline+comments">"multiline comments"</url>
          </p>
        </li>
      </ul>
    </p>
  </aside>

  <insight>
    <idx><h>Insights</h><h>disabling code</h></idx>
    <p>
      Comments are also used to temporarily <term>disable</term> lines of code.
    </p>
  </insight>

  <p>
    For example:
  </p>

  <sage language="python">
    <input>
      # This is a comment

      print("This is code")

      #print("This code will not run")

      print("More code") # A comment can be after code
    </input>
  </sage>

  <aside>
    <title>Try It Out</title>
    
    <p>
      Try removing the <c>#</c> in line 5 and re-run the code.
    </p>
  </aside>

  <problem>
    <pre>
      This is code
      More code
    </pre>
  </problem>

  <investigation>
    <idx><h>Code examples</h><h>comments</h></idx>
    <p></p>
    <p>
      Line 1 is a comment used to leave notes.
    </p>
    <p>
      Lines 3 and 7 are normal code.
    </p>
    <p>
      Line 5 is a comment used to <q>disable</q> code.
    </p>
  </investigation>

  <p>
    <cd>
    </cd>
  </p>

  <exploration>
    <title>Basic Programming <mdash /> Part 4: Comments</title>
    <idx><h>Videos</h><h>part 04</h></idx>
    
    <video youtube="JkK5rQ8Hyzg" />
      
  </exploration>

</section>