Skip to main content
Engineering LibreTexts

2.3: Comments are Required

  • Page ID
    29016
  • \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \) \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)\(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\) \(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\)\(\newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    You Have to Make a Comment

    Comments are VERY useful in attempting to read someone else's code. There are many different methods for writing comments, and for the most part it depends on what your organization requires. Most organizations have "coding standards", a document that explains exactly how ALL software developed by any programmer working for that organization is to look.

    As previously mentioned, comments have various formats depending on your organizations requirements.

    • Explain how a function is used. Provide a brief explanation of what the function does. This simply states what the function does, what the argument list is, and what the function returns. Notice the multi-line format of the comment. The asterisk before each line is not required, but this is a common format. Usually, unless the code in this function is overly complex, you do not have to go into detail about what the function does.
      /*
      * Read an image from disk.
      *
      * fileName the file to read. Must be either absolute or relative to
      *     the program working directory.
      *
      * return the image stored in `fileName`. If the image on disk does not
      *     have `double` pixels, they will be cast to `double`.
      *
      * throws IoError Thrown if `fileName` does not exist or is not readable.
      */
      lsst::afw::image::Image<double> loadImage(std::string const & fileName);
      
    • Explain complicated code - I have NO idea what this comment even says, but am sure the code is pretty gnarly.
      /*
       * The FFT is a fast implementation of the discrete Fourier transform:
       * @f[ X(e^{j\omega } ) = x(n)e^{ - j\omega n} @f]
       */
    • Communicate meta-information - meta-information is information about the overall file or project...not specifically about the code. You usually see such comments at the beginning of the main packages of a large project.
      /*
       * This file is part of Telescope Directional Drive package.
       *
       * Developed for the LSST Data Management System.
       * This product includes software developed by the LSST Project
       * (https://www.lsst.org).
       * See the COPYRIGHT file at the top-level directory of this distribution
       * for details of code ownership.
       *
       * This program is free software: you can redistribute it and/or modify
       * it under the terms of the GNU General Public License as published by
       * the Free Software Foundation, either version 3 of the License, or
       * (at your option) any later version.
       *
       * This program is distributed in the hope that it will be useful,
       * but WITHOUT ANY WARRANTY; without even the implied warranty of
       * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       * GNU General Public License for more details.
       */
    • Ad-hoc Comments. Simple comments, this does not really add anything to the code, unless it is required by documentation standards should not be included.
      // Sum two numbers.
      double add(double a, double b);
      
      These next two are the same - comments can be on the same line as the code. 
      Anything from the // to the end of the line is a comment
      /// Flag set if background subtraction should not be done.
      const int NO_BACKGROUND = 1 << 3;
      OR
      const int NO_BACKGROUND = 1 << 3;        ///< Skip background subtraction
      
      

     

    Documentation examples: "Documenting C++ Code" by LSST DM staff, Legacy Survey of Space and Time , Rubin Observatory is licensed under CC BY 4.0


    This page titled 2.3: Comments are Required is shared under a CC BY-SA license and was authored, remixed, and/or curated by Patrick McClanahan.