1. 10
    Commenting Showing Intent [CSI] ☶ practices programming standards.mousepawmedia.com
    quobit avatar via quobit 1 year ago | cached | 4 comments

The CSI (Commenting Showing Intent) Commenting Standards refers to a style of code commenting which allows for the complete rewriting of a program in any language, given only the comments. It is also a backhanded reference to Crime Scene Investigation: putting the clues together to recreate the whole event.

  1.  

  2. 3
    JohnCarter avatar JohnCarter 1 year ago | link

    I agree with the CSI standard…..

    Actually the most interesting things on that site are https://standards.mousepawmedia.com/lit.html

    The main principle behind the Live-In Testing Standard is that all tests are built into the code being tested, and are compiled alongside of it. Tests are executed while the program is running.

    There are several distinct advantages to this:

    • Tests can be shipped with the software. Tech support can instruct users to run tests, in order to generate specific and useful debugging information. This information can in turn be used to fix the problem over the phone, or provide the necessary details to file a bug report.
    • It is easier to extract useful information from a test output than from a log file.
    • Benchmarking and (most) testing can be performed on all supported systems without the need to install special tools or applications.

    And https://standards.mousepawmedia.com/qtm.html

    Quantified Task Management [QTM]

    Lots of good stuff, but the really new idea (to me) is…

    Relativity/Black Hole Probability (Uncertainty)

    It can be easy to predict how much effort and time will go into a task, or it can be very hard. Relativity is essentially a measure of how accurate the predictions are. A task becomes a black hole when you have absolutely no idea how much time the task will take.

    A good rule of thumb: you will know the relativity within the first hour of working on a task.

    • r0: No chance of black hole. No relativity.
    • r1: Low black hole probability. Low relativity.
    • r2: Moderate black hole probability. Moderate relativity.
    • r3: High black hole probability. High relativity.
    • r4: Definite black hole. Total relativity.
    • r5: Collapsing. Task needs to be abandoned or re-factored - it is probably impossible in its current state.
    1. 0
      data_hope avatar data_hope 1 year ago | link

      Quickly skimming through this document, it doesn’t really contain my favourite Commenting guideline: Use speaking identifiers as much as possible, don’t write a comment, if you can express the same information using good naming and proper structure in the program.

      1. 3
        jclulow avatar jclulow 1 year ago | link

        I think it does actually address that concept, under the name “self-commenting code”.

        1. 1
          data_hope avatar data_hope 1 year ago | link

          you are right. It’s there.