Commenting styles, I have a dream


#1

I have a dream that those coders still commenting this way would stop!

/* Stop It !!! */

It’s absurd to comment like this, when you can do the following which takes less typing, and more importantly, should you need to comment out a block of code surrounding it with “/* */” you cant.

Start commenting this way.
// Use this way

Still not convinced /* bla…bla…bla… */ its a horrid way to comment?
Lets take a look at an example then…
This snipped of code is using the bad way to comment.

uint8_t msb;
uint8_t lsb;
uint8_t xlsb;
cmd = i2c_cmd_link_create();     /* Lets create the link here */
i2c_master_start(cmd);              /* Start I2c */
i2c_master_write_byte(cmd, (BMP180_ADDRESS << 1) | I2C_MASTER_READ, 1);
i2c_master_read_byte(cmd, &msb, 1);   /* Read first byte back */
i2c_master_read_byte(cmd, &lsb, 1);    /* Read second byte back */
i2c_master_read_byte(cmd, &xlsb, 0);  /* Read third byte back */
i2c_master_stop(cmd);
i2c_master_cmd_begin(I2C_NUM_0, cmd, 1000/portTICK_PERIOD_MS);
i2c_cmd_link_delete(cmd);
int ret = (int)((msb << 16) | (lsb << 8) | xlsb);
return ret;

Now, for whatever reason, should I need to comment out this block of code, or parts of it I cannot quickly do it. However, If the same block of code using “//” commenting would be very quick and easy to block it out.


//    All this is now blocked out with just 4 keystrokes!!! 

uint8_t msb;
uint8_t lsb;
uint8_t xlsb;
cmd = i2c_cmd_link_create();     // Lets create the link here 
i2c_master_start(cmd);              // Start I2c 
i2c_master_write_byte(cmd, (BMP180_ADDRESS << 1) | I2C_MASTER_READ, 1 );
i2c_master_read_byte(cmd, &msb, 1);   // Read first byte back 
i2c_master_read_byte(cmd, &lsb, 1);    // Read second byte back 
i2c_master_read_byte(cmd, &xlsb, 0);  // Read third byte back 
i2c_master_stop(cmd);
i2c_master_cmd_begin(I2C_NUM_0, cmd, 1000/portTICK_PERIOD_MS);
i2c_cmd_link_delete(cmd);
int ret = (int)((msb << 16) | (lsb << 8) | xlsb);
return ret;

Or partial block like this:

    uint8_t msb;
    uint8_t lsb;
    uint8_t xlsb;
    cmd = i2c_cmd_link_create();     // Lets create the link here 
    i2c_master_start(cmd);              // Start I2c 
    i2c_master_write_byte(cmd, (BMP180_ADDRESS << 1) | I2C_MASTER_READ, 1 );
    /*
    i2c_master_read_byte(cmd, &msb, 1);   // Read first byte back 
    i2c_master_read_byte(cmd, &lsb, 1);    // Read second byte back 
    i2c_master_read_byte(cmd, &xlsb, 0);  // Read third byte back 
    */
    i2c_master_stop(cmd);
    i2c_master_cmd_begin(I2C_NUM_0, cmd, 1000/portTICK_PERIOD_MS);
    i2c_cmd_link_delete(cmd);
    int ret = (int)((msb << 16) | (lsb << 8) | xlsb);
    return ret;

Get why now?


closed #21

This topic was automatically closed after 44 hours. New replies are no longer allowed.