Need more break, hence more went....
-
In my days C "entry" was limited to 32 characters... I do not care to know current limit, but if the coder writes descriptive function title / name "Setup_And_Activate_Serial_Port(..." does she / he has a valid excuse NOT to write ANY / nill /nada / nichevo / zilch / zadnej(zadnou) function description ??? Cheers
-
In my days C "entry" was limited to 32 characters... I do not care to know current limit, but if the coder writes descriptive function title / name "Setup_And_Activate_Serial_Port(..." does she / he has a valid excuse NOT to write ANY / nill /nada / nichevo / zilch / zadnej(zadnou) function description ??? Cheers
-
In my days C "entry" was limited to 32 characters... I do not care to know current limit, but if the coder writes descriptive function title / name "Setup_And_Activate_Serial_Port(..." does she / he has a valid excuse NOT to write ANY / nill /nada / nichevo / zilch / zadnej(zadnou) function description ??? Cheers
Many years ago (even years before Linux!) I worked with a company writing their own OS. A complete rewrite was made in a (proprietary) high level language, embraced by the old assembly programmers because "Now we don't have to write comments any more!" It is at the same level as one introduction to COBOL-60 declaring that with this language, there is no longer a need for specially trained programmers; now anyone can write the solution in plain English language. With a name like Setup_And_Activate_Serial_Port, there is no need for the comment to explain that this function will set up and activate a serial port. If the arguments have similarly descriptive names, you need not, in the comments, repeat what the name reveals. But I very rarely if ever see function definitions where all and everything of what the code maintainer ought to know can be expressed in the name alone (with a possible exception for 1-2 line bodies). So there is usually a need to document a lot of other aspects. The comment associated with the function heading I prefer to keep short; it is for the user of the function, not the maintainer. And I love end-of-line comments: At the exact spot it applies to, and it won't cause the function body to spread over multiple screenfuls. (But with all EOL comments running from col 70 or 80, so they don't blur the code, you may need to widen your editor window or use the horizontal scroll bar to see them.) For some reason, most programmers disagree with me. Generally speaking: These huge comment blocks above the function, essentially repeating information already present in (good) naming, and very little extra info, I think of as plain LOC boosters. They are no excuse whatsoever for not commenting non-obvious issues through the code (although they are often used for that purpose :-)). Two thirds of all the code comments I see have no value whatsoever, and at least two thirds of the issues that really could need an explanatory comment is left as plain, uncommented code. If I were to grade coders by their comments, very few would even reach a 'C'. Quite a few would flunk.
-
When I started, you could only have 8 "significant characters" in function or variable name. Nowadays that is not a problem but I still don't like long descriptive function names. I prefer short functions that you can understand with one look.
jhaga
I certainly would prefer two functions "Setup_Serial_Port" and "Activate_Serial_Port" :-) (I like short function bodies, too!). In an OO environment, I would accept (even prefer) methods "Setup" and "Activate" on a Serial_Port object. But I would not accept "SSP" and "ASP" (or "SAASP"), even if that would save a few keystrokes when you make a call.
-
What is "entry" and why is it quoted?
"One man's wage rise is another man's price increase." - Harold Wilson
"Fireproof doesn't mean the fire will never come. It means when the fire comes that you will be able to withstand it." - Michael Simmons
"You can easily judge the character of a man by how he treats those who can do nothing for him." - James D. Miles
Old assembly programmers often refer to a function's "entry point"- the code location where function execution is entered. The function name is the label assigned to this code location, often referred to as the "entry". In assembler code it was not uncommon for a function to have multiple entry points. There were even high level languages allowing a function to have several entry points. One use was to call the function first time at an entry doing a lot of initialization before the "real work". Later calls used an entry point right at the "real work" part. Obviously, you could do the same with an "if not initialized, then ...", or in an OO world using a constructor, but in the old days it was different. In *nix, you may consider it a functional equivalent of multiple entry points if an executable inspects argument zero, the name given to the executable file, using it to switch to different parts of the code, often as different setups before going on to the same "real work" part for all alternatives. "Entry" is (or was) used for any location you could jump to, not just the start of a function. Few programmers make use of labels today, but I guess the limitation on 32 char length applied to labels as well as functions. So the OP used "entry"
-
What is "entry" and why is it quoted?
"One man's wage rise is another man's price increase." - Harold Wilson
"Fireproof doesn't mean the fire will never come. It means when the fire comes that you will be able to withstand it." - Michael Simmons
"You can easily judge the character of a man by how he treats those who can do nothing for him." - James D. Miles
Old assembly programmers often refer to a function's "entry point"- the code location where function execution is entered. The function name is the label assigned to this code location, often referred to as the "entry". In assembler code it was not uncommon for a function to have multiple entry points. There were even high level languages allowing a function offering it. One use was to call the function first time at an entry doing a lot of initialization before the "real work". Later calls used an entry point right at the "real work" part. Obviously, you could do the same with an "if not initialized, then ...", or in an OO world using a constructor, but in the old days it was different. In *nix, you may consider it a functional equivalent of multiple entry points if an executable inspects argument zero, the name given to the executable file, using it to switch to different parts of the code, often as different setups before going on to the same "real work" part for all alternatives. Wikipedia discusses "Entry point" only as the entry point for the entire executable ("main" or its equivalent), not for a function. This is a restriction of the discussion; earlier, referring to the function's entry point was common, accepted terminology. (Googling for "function entry point" returns quite a few hits!) "Entry" is (or was) used for any location you could jump to, not just the start of a function. Few programmers make use of labels today, but I guess the limitation on 32 char length applied to labels as well as functions. So the OP used "entry" as a common term for both, and as neither is really called "entry", the quoting (to mark that this is not the real term) is appropriate.
-
Many years ago (even years before Linux!) I worked with a company writing their own OS. A complete rewrite was made in a (proprietary) high level language, embraced by the old assembly programmers because "Now we don't have to write comments any more!" It is at the same level as one introduction to COBOL-60 declaring that with this language, there is no longer a need for specially trained programmers; now anyone can write the solution in plain English language. With a name like Setup_And_Activate_Serial_Port, there is no need for the comment to explain that this function will set up and activate a serial port. If the arguments have similarly descriptive names, you need not, in the comments, repeat what the name reveals. But I very rarely if ever see function definitions where all and everything of what the code maintainer ought to know can be expressed in the name alone (with a possible exception for 1-2 line bodies). So there is usually a need to document a lot of other aspects. The comment associated with the function heading I prefer to keep short; it is for the user of the function, not the maintainer. And I love end-of-line comments: At the exact spot it applies to, and it won't cause the function body to spread over multiple screenfuls. (But with all EOL comments running from col 70 or 80, so they don't blur the code, you may need to widen your editor window or use the horizontal scroll bar to see them.) For some reason, most programmers disagree with me. Generally speaking: These huge comment blocks above the function, essentially repeating information already present in (good) naming, and very little extra info, I think of as plain LOC boosters. They are no excuse whatsoever for not commenting non-obvious issues through the code (although they are often used for that purpose :-)). Two thirds of all the code comments I see have no value whatsoever, and at least two thirds of the issues that really could need an explanatory comment is left as plain, uncommented code. If I were to grade coders by their comments, very few would even reach a 'C'. Quite a few would flunk.
I just "discovered" , OK somebody smarter than me figured it out , probably after reading the "library" source code...that "Custom" means "autocomplete the entry ( text ) using what is already on the list ".... Double trouble both the "autocomplete" feature and definitely no real "Custom" options are nowhere mentioned , in an example code or in the documentation of the class.... Would somebody "write" AI application to annotate undocumented gems like this one? PLEASE
-
Many years ago (even years before Linux!) I worked with a company writing their own OS. A complete rewrite was made in a (proprietary) high level language, embraced by the old assembly programmers because "Now we don't have to write comments any more!" It is at the same level as one introduction to COBOL-60 declaring that with this language, there is no longer a need for specially trained programmers; now anyone can write the solution in plain English language. With a name like Setup_And_Activate_Serial_Port, there is no need for the comment to explain that this function will set up and activate a serial port. If the arguments have similarly descriptive names, you need not, in the comments, repeat what the name reveals. But I very rarely if ever see function definitions where all and everything of what the code maintainer ought to know can be expressed in the name alone (with a possible exception for 1-2 line bodies). So there is usually a need to document a lot of other aspects. The comment associated with the function heading I prefer to keep short; it is for the user of the function, not the maintainer. And I love end-of-line comments: At the exact spot it applies to, and it won't cause the function body to spread over multiple screenfuls. (But with all EOL comments running from col 70 or 80, so they don't blur the code, you may need to widen your editor window or use the horizontal scroll bar to see them.) For some reason, most programmers disagree with me. Generally speaking: These huge comment blocks above the function, essentially repeating information already present in (good) naming, and very little extra info, I think of as plain LOC boosters. They are no excuse whatsoever for not commenting non-obvious issues through the code (although they are often used for that purpose :-)). Two thirds of all the code comments I see have no value whatsoever, and at least two thirds of the issues that really could need an explanatory comment is left as plain, uncommented code. If I were to grade coders by their comments, very few would even reach a 'C'. Quite a few would flunk.
I used to work for a company that completely discarded the comments in the code on behalf of self-explanatory names and short functions(C++/C#). I also worked for another one where it was expected that we write a small novel on top of every function(C/Java). I like the former approach better.
Advertise here – minimum three posts per day are guaranteed.
-
I used to work for a company that completely discarded the comments in the code on behalf of self-explanatory names and short functions(C++/C#). I also worked for another one where it was expected that we write a small novel on top of every function(C/Java). I like the former approach better.
Advertise here – minimum three posts per day are guaranteed.
Of course the second allows one to document things like expectations, current usage and unusual usages that come about when one ends up maintaining legacy code written by someone that left the company 10 years ago and figured keeping all that domain knowledge in their head was the sign of a professional.
-
Many years ago (even years before Linux!) I worked with a company writing their own OS. A complete rewrite was made in a (proprietary) high level language, embraced by the old assembly programmers because "Now we don't have to write comments any more!" It is at the same level as one introduction to COBOL-60 declaring that with this language, there is no longer a need for specially trained programmers; now anyone can write the solution in plain English language. With a name like Setup_And_Activate_Serial_Port, there is no need for the comment to explain that this function will set up and activate a serial port. If the arguments have similarly descriptive names, you need not, in the comments, repeat what the name reveals. But I very rarely if ever see function definitions where all and everything of what the code maintainer ought to know can be expressed in the name alone (with a possible exception for 1-2 line bodies). So there is usually a need to document a lot of other aspects. The comment associated with the function heading I prefer to keep short; it is for the user of the function, not the maintainer. And I love end-of-line comments: At the exact spot it applies to, and it won't cause the function body to spread over multiple screenfuls. (But with all EOL comments running from col 70 or 80, so they don't blur the code, you may need to widen your editor window or use the horizontal scroll bar to see them.) For some reason, most programmers disagree with me. Generally speaking: These huge comment blocks above the function, essentially repeating information already present in (good) naming, and very little extra info, I think of as plain LOC boosters. They are no excuse whatsoever for not commenting non-obvious issues through the code (although they are often used for that purpose :-)). Two thirds of all the code comments I see have no value whatsoever, and at least two thirds of the issues that really could need an explanatory comment is left as plain, uncommented code. If I were to grade coders by their comments, very few would even reach a 'C'. Quite a few would flunk.
trønderen wrote:
you may need to widen your editor window or use the horizontal scroll bar to see them.) For some reason, most programmers disagree with me.
That is not an option on a VT screen. Similarly, some systems such as Oracle's PRO*C put a limit on line lengths. Personally, I prefer not to exceed 112 characters because that's how many I can fit on a page.
-
trønderen wrote:
you may need to widen your editor window or use the horizontal scroll bar to see them.) For some reason, most programmers disagree with me.
That is not an option on a VT screen. Similarly, some systems such as Oracle's PRO*C put a limit on line lengths. Personally, I prefer not to exceed 112 characters because that's how many I can fit on a page.
PIEBALDconsult wrote:
That is not an option on a VT screen.
What year was the most recent VT terminal released? Wikipedia describes the 1993 VT520 (i.e. 30 years ago), discontinued 10 years later (20 years ago). I doubt that there were later VT screens. According to Wikipedia, the 1987 VT320 (and its successors) could display 132 chars/line, leaving room for 62 chars of end-of-line comments starting at col 70. In the age of non-graphic, character oriented screens, it was commonplace for editors to provide a command to move the window to the right by, say, 20 or 40 characters. For the first generation of character screens, the entire screen had to be redrawn. More 'recent' models provided escape sequences for moving the contents in a line buffer (in the terminal) to the right or left, so only the new part had to be transmitted. Editors of the time fine-tuned their output to the terminal model in use, to reduce data transmitted.
Similarly, some systems such as Oracle's PRO*C put a limit on line lengths.
They can't possibly have had a limit less than 132! I worked with editors having a 256 char limit, some time in the 1980s. I googled 'Oracle PRO*C', and was sent to the documentation for version 12.1; it seems to be released in 2014. At that time, the 'Precompiler options' documentation for MAXLITERAL states The maximum value of MAXLITERAL is compiler dependent. For example, some C compilers cannot handle string literals longer than 512 characters, so you would specify MAXLITERAL=512. This is a (semi-)reasonable limit, but not one preventing you from using end-of-line comments! The limit may of course have been lower in earlier years (e.g. 256), but if a compiler couldn't process a source file that could be printed on 'any' line printer of the day, it must be classified as a toy compiler. (Besides, for EOL comments, the compiler sets no limits - the preprocessor strips off all comments, EOL or otherwise! So the limitation would be in the preprocessor, and I doubt very much that it had any limit affecting EOL comments.) A note from modern times (5-6 years ago): The company I worked for was revising its C coding rules. The working group had suggested that all source files be limited to a maximum of 80 characters. At the meeting where this proposal was presented, my project leader immediately jumped up and declared that our project would have an exemption from this rule. The main reason: We had