How to understand the code which wrote by someone??
See, those are exactly the sort of comments you should NEVER write. (If you need them as a crutch, fine, but delete them when the code is written.)
What frightens me more than anything is when a coder will begin a project without sufficient planning. No, the whole project doesnt need to be planned as this itself can lead to problems, but in agreeance with Adam Hamilton, a comment-structure can very quickly organize a method, function, or entire program. What I can't entirely fathom is how some of you can say "perfect code" (which doesn't exist due to others definition of perfection) does not contain comments. Mathematical algorithms can be extremely complicated, and reading through their source even when "perfectly" coded can prove a daunting task. Then again, leading a block of code with an explanation which is obvious by the succeeding code is not wrong as it organizes code into structured blocks, which is the foundation of some languages/scripts such as XHTML.
If you're refering to "speed" as in the speed to write out the program, then I agree. Yet, if you are refering to the speed of the program you must take into account that compilers strip comments, whereby they have no effect on runtime speeds.
To eniCma:
In my humble opinion one of the best ways to understand someone elses code is to firstly block it into major code sections (usually methods and functions) and understand the structure of the program before delving into the individual lines of code. Once the structure is understood do the same with each function starting from square one, and understand what each line is attempting to do. Bare also in mind, for you "perfect coders" that although you understand what is going on in a segment of code, a comment obvious to you could save someone like eniCma a lot of trouble in understanding what is going on.
Then again.. everything falls down to your programming goals: Maintainability, speed, portability... readability...
Quote:Original post by Ezbez
I disagree that no code ever needs comments, if perfectly written. Sometimes (rarely) speed *is* the most important factor, readablility will be sacrificed, and a couple of comments may do just the trick.
If you're refering to "speed" as in the speed to write out the program, then I agree. Yet, if you are refering to the speed of the program you must take into account that compilers strip comments, whereby they have no effect on runtime speeds.
To eniCma:
In my humble opinion one of the best ways to understand someone elses code is to firstly block it into major code sections (usually methods and functions) and understand the structure of the program before delving into the individual lines of code. Once the structure is understood do the same with each function starting from square one, and understand what each line is attempting to do. Bare also in mind, for you "perfect coders" that although you understand what is going on in a segment of code, a comment obvious to you could save someone like eniCma a lot of trouble in understanding what is going on.
Then again.. everything falls down to your programming goals: Maintainability, speed, portability... readability...
Author
Thank you for everyone...
So, we let do the real practice now!!
I copy this code from C Programming (K&R) in topic "Pointers to Function"
#include <stdio.h>
#include <string.h>
#define MAXLINES 5000 /* max #lines to be sorted */
char *lineptr[MAXLINES]; /* pointers to text lines */
int readlines(char *lineptr[], int nlines);
void writelines(char *lineptr[], int nlines);
void qsort(void *lineptr[], int left, int right,
int (*comp)(void *, void *));
int numcmp(char *, char *);
/* sort input lines */
main(int argc, char *argv[])
{
int nlines; /* number of input lines read */
int numeric = 0; /* 1 if numeric sort */
if (argc > 1 && strcmp(argv[1], "-n") == 0)
numeric = 1;
if ((nlines = readlines(lineptr, MAXLINES)) >= 0) {
qsort((void**) lineptr, 0, nlines-1,
(int (*)(void*,void*))(numeric ? numcmp : strcmp));
writelines(lineptr, nlines);
return 0;
} else {
printf("input too big to sort\n");
return 1;
}
}
==========================
For my trouble, when I first saw any code such as like this code (complex & a lot of nest if/loop), I felling very confuse.. 1st question in mind..how I can start to figure out each line or purpose of code?
NOW! Follow all of your above comment.... I begin to finding "comment" & "structure porgam" ... and "see the Fucntions"...
This is my summary...
- This code demonstrate "Pointer to function" concept
- There are four function in this code.. (readlines, writelines, qsort and numcmp)
- Then the code read input line & going into main( )... then if if if
- It's seem that from line...
if (argc > 1 && strcmp(argv[1], "-n") == 0)
numeric = 1;
if ((nlines = readlines(lineptr, MAXLINES)) >= 0) {
qsort((void**) lineptr, 0, nlines-1,
(int (*)(void*,void*))(numeric ? numcmp : strcmp));
writelines(lineptr, nlines);
return 0;
} else {
printf("input too big to sort\n");
return 1;
}
I don't know the mechanical of each line (because it doesn't have comment, so this is bad practice programming?)...
However, I can figure out what is the command on each line but... don't know "why we do that???..." Not sure... It's seem that I am poor of generic algorithm knowledge now??? right?
This is mt trouble that I said ... :(
Any comments are welcome.
So, we let do the real practice now!!
I copy this code from C Programming (K&R) in topic "Pointers to Function"
#include <stdio.h>
#include <string.h>
#define MAXLINES 5000 /* max #lines to be sorted */
char *lineptr[MAXLINES]; /* pointers to text lines */
int readlines(char *lineptr[], int nlines);
void writelines(char *lineptr[], int nlines);
void qsort(void *lineptr[], int left, int right,
int (*comp)(void *, void *));
int numcmp(char *, char *);
/* sort input lines */
main(int argc, char *argv[])
{
int nlines; /* number of input lines read */
int numeric = 0; /* 1 if numeric sort */
if (argc > 1 && strcmp(argv[1], "-n") == 0)
numeric = 1;
if ((nlines = readlines(lineptr, MAXLINES)) >= 0) {
qsort((void**) lineptr, 0, nlines-1,
(int (*)(void*,void*))(numeric ? numcmp : strcmp));
writelines(lineptr, nlines);
return 0;
} else {
printf("input too big to sort\n");
return 1;
}
}
==========================
For my trouble, when I first saw any code such as like this code (complex & a lot of nest if/loop), I felling very confuse.. 1st question in mind..how I can start to figure out each line or purpose of code?
NOW! Follow all of your above comment.... I begin to finding "comment" & "structure porgam" ... and "see the Fucntions"...
This is my summary...
- This code demonstrate "Pointer to function" concept
- There are four function in this code.. (readlines, writelines, qsort and numcmp)
- Then the code read input line & going into main( )... then if if if
- It's seem that from line...
if (argc > 1 && strcmp(argv[1], "-n") == 0)
numeric = 1;
if ((nlines = readlines(lineptr, MAXLINES)) >= 0) {
qsort((void**) lineptr, 0, nlines-1,
(int (*)(void*,void*))(numeric ? numcmp : strcmp));
writelines(lineptr, nlines);
return 0;
} else {
printf("input too big to sort\n");
return 1;
}
I don't know the mechanical of each line (because it doesn't have comment, so this is bad practice programming?)...
However, I can figure out what is the command on each line but... don't know "why we do that???..." Not sure... It's seem that I am poor of generic algorithm knowledge now??? right?
This is mt trouble that I said ... :(
Any comments are welcome.
OK let's try it.
//uses string and io routines
#include <stdio.h>
#include <string.h>
//seems to be used for sorting text lines
#define MAXLINES 5000 /* max #lines to be sorted */
char *lineptr[MAXLINES]; /* pointers to text lines */
//reads a number lines from the pointer array
int readlines(char *lineptr[], int nlines);
//writes a number of lines to the pointer array
void writelines(char *lineptr[], int nlines);
//Quicksort on the line array?
void qsort(void *lineptr[], int left, int right,
int (*comp)(void *, void *));
//Function for comparing strings numerically?
int numcmp(char *, char *);
/* sort input lines */
main(int argc, char *argv[])
{
int nlines; /* number of input lines read */
int numeric = 0; /* 1 if numeric sort */
//read the comandline arguments and check for -n option?
if (argc > 1 && strcmp(argv[1], "-n") == 0)
numeric = 1;
//try to read the lines
if ((nlines = readlines(lineptr, MAXLINES)) >= 0) {
//if lines could be read, sort them. Use compare function based on "numeric" variable
qsort((void**) lineptr, 0, nlines-1,
(int (*)(void*,void*))(numeric ? numcmp : strcmp));
//write the sorted lines somewhere
writelines(lineptr, nlines);
return 0;
} else {
//lines could not be read
printf("input too big to sort\n");
return 1;
}
}
OK, that code seems to read some text lines, sort them with Quicksort based on text or numerical comparinsons (depends on commandline option -n), an writes the sorted text somewhere.
So now the questions:
Where do the lines come from?
Where are they written to?
That should be answered by the implementations of the functions "readlines" and "writelines".
[Edited by - Lord_Evil on September 22, 2006 5:03:09 AM]
//uses string and io routines
#include <stdio.h>
#include <string.h>
//seems to be used for sorting text lines
#define MAXLINES 5000 /* max #lines to be sorted */
char *lineptr[MAXLINES]; /* pointers to text lines */
//reads a number lines from the pointer array
int readlines(char *lineptr[], int nlines);
//writes a number of lines to the pointer array
void writelines(char *lineptr[], int nlines);
//Quicksort on the line array?
void qsort(void *lineptr[], int left, int right,
int (*comp)(void *, void *));
//Function for comparing strings numerically?
int numcmp(char *, char *);
/* sort input lines */
main(int argc, char *argv[])
{
int nlines; /* number of input lines read */
int numeric = 0; /* 1 if numeric sort */
//read the comandline arguments and check for -n option?
if (argc > 1 && strcmp(argv[1], "-n") == 0)
numeric = 1;
//try to read the lines
if ((nlines = readlines(lineptr, MAXLINES)) >= 0) {
//if lines could be read, sort them. Use compare function based on "numeric" variable
qsort((void**) lineptr, 0, nlines-1,
(int (*)(void*,void*))(numeric ? numcmp : strcmp));
//write the sorted lines somewhere
writelines(lineptr, nlines);
return 0;
} else {
//lines could not be read
printf("input too big to sort\n");
return 1;
}
}
OK, that code seems to read some text lines, sort them with Quicksort based on text or numerical comparinsons (depends on commandline option -n), an writes the sorted text somewhere.
So now the questions:
Where do the lines come from?
Where are they written to?
That should be answered by the implementations of the functions "readlines" and "writelines".
[Edited by - Lord_Evil on September 22, 2006 5:03:09 AM]
I agree that perfect code would require no comments whatsoever. The stated reasons for objecting to this seem to be implying that commenting code is the only way to express the author(s) intention. This isn't the case, though, as the language itself lets you express intent. Clean structure and good names can convey oodles of information about what's going on, and in appropriately bite-sized pieces.
In almost all of my code, almost all of the comments are function-header comments, and those are mostly there to provide easy-on-the-eyes separators between functions. Most of the other comments are to explain why an odd construct or approach was taken, or to warn the user about some potentially unexpected or dangerous behavior.
In almost all of my code, almost all of the comments are function-header comments, and those are mostly there to provide easy-on-the-eyes separators between functions. Most of the other comments are to explain why an odd construct or approach was taken, or to warn the user about some potentially unexpected or dangerous behavior.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement