Skip to contentSkip to conversation

Which comments is unnessary?

DISCUSSION Navy 2 participants 2 messages Jul 14, 2015

lore
Share & tools
lore

Navy

author
#0 lore raw

Hi,
Here is a code fragment, which comments is unnessary? I think the all the comments should be remove because the comments should show "What to do rather than "How to do?". Am I right?

/************************************************************************
* Unit flag definitions for un_flags. ************************************************************************/
#define UN_ISOPEN 0x0001 /* Device is open */
#define UN_CLOSING 0x0002 /* Line is being closed */
#define UN_IMM 0x0004 /* Service immediately */
#define UN_BUSY 0x0008 /* Some work this channel */
#define UN_BREAKI 0x0010 /* Input break received */
#define UN_PWAIT 0x0020 /* Printer waiting for terminal */
#define UN_TIME 0x0040 /* Waiting on time */
#define UN_EMPTY 0x0080 /* Waiting output queue empty */
#define UN_LOW 0x0100 /* Waiting output low water mark*/
#define UN_EXCL_OPEN 0x0200 /* Open for exclusive use */
#define UN_WOPEN 0x0400 /* Device waiting for open */
#define UN_WIOCTL 0x0800 /* Device waiting for open */
#define UN_HANGUP 0x8000 /* Carrier lost */

struct device;

/************************************************************************
* Structure for terminal or printer unit. ************************************************************************/

struct un_t {
	int	magic;		/* Unit Magic Number.			*/
	struct	channel_t *un_ch;
	ulong	un_time;
	uint	un_type;
	uint	un_open_count;	/* Counter of opens to port		*/
	struct tty_struct *un_tty;/* Pointer to unit tty structure	*/
	uint	un_flags;	/* Unit flags				*/
	wait_queue_head_t un_flags_wait; /* Place to sleep to wait on unit */
	uint	un_dev;		/* Minor device number			*/
	struct device *un_sysfs;
};
#1 lore raw

Seems to me that every comment there is useful to someone who might come along later and try to understand that piece of code, and what it's doing.

Quoted 44 lines · Navy

Hi,
Here is a code fragment, which comments is unnessary? I think the all the comments should be remove because the comments should show "What to do rather than "How to do?". Am I right?

/************************************************************************
* Unit flag definitions for un_flags. ************************************************************************/
#define UN_ISOPEN 0x0001 /* Device is open */
#define UN_CLOSING 0x0002 /* Line is being closed */
#define UN_IMM 0x0004 /* Service immediately */
#define UN_BUSY 0x0008 /* Some work this channel */
#define UN_BREAKI 0x0010 /* Input break received */
#define UN_PWAIT 0x0020 /* Printer waiting for terminal */
#define UN_TIME 0x0040 /* Waiting on time */
#define UN_EMPTY 0x0080 /* Waiting output queue empty */
#define UN_LOW 0x0100 /* Waiting output low water mark*/
#define UN_EXCL_OPEN 0x0200 /* Open for exclusive use */
#define UN_WOPEN 0x0400 /* Device waiting for open */
#define UN_WIOCTL 0x0800 /* Device waiting for open */
#define UN_HANGUP 0x8000 /* Carrier lost */

struct device;

/************************************************************************
* Structure for terminal or printer unit. ************************************************************************/

struct un_t {
	int	magic;		/* Unit Magic Number.			*/
	struct	channel_t *un_ch;
	ulong	un_time;
	uint	un_type;
	uint	un_open_count;	/* Counter of opens to port		*/
	struct tty_struct *un_tty;/* Pointer to unit tty structure	*/
	uint	un_flags;	/* Unit flags				*/
	wait_queue_head_t un_flags_wait; /* Place to sleep to wait on unit */
	uint	un_dev;		/* Minor device number			*/
	struct device *un_sysfs;
};

_______________________________________________
Kernelnewbies mailing list
Kernelnewbies at kernelnewbies.org
http://lists.kernelnewbies.org/mailman/listinfo/kernelnewbies

Signature · 2 lines
In theory, there is no difference between theory and practice.
In practice, there is.   .... Yogi Berra