CODING QUESTION: What is the MOST importanting thing to do when......

[Fasola]

What is the MOST important thing to do when developing new code or modifying existing code (other than correct functionality)? Why?

I was asked this question today as part of a test for a Software Engineer job, i think its an opinion based question with no correct answer. Help me out and tell me what you think the answer is

[Dave Sinkula]

I'd say comment it well would be right up there.

[Fasola]

^^^

That's important, doesn't sound like it would be MOST important after functionality?

Still a good answer though

[Narue]

>What is the MOST important thing to do when developing new code or modifying existing code
Understand the problem to be solved, of course. This takes precedence over everything, including correct functionality.

>Why?
If you don't understand the problem, you can't possibly develop a new program or modify an existing program that solves the problem correctly.

[Fasola]

Understand the problem to be solved

I don't feel like such a "silly goof" now, because that was my answer too

[Dave Sinkula]

>because that was my answer too

Me, too! [That's what this is going to sound like.]

The "understand the problem" is a bit of what I was trying to say with "comment it well". That is, if you can describe the problem and solution in the comments, you probably understand the problem. And so can all the other eyes that will review the code.

Since it wasn't that clear, I guess that shows that my comments were poor. :(

This is something I found lying around*; hopefully it is unfamliar. It is meant to be an example of what I mean by commenting it well (I hope).

/*******************************************************************************
 * Description:
 *   A compile-time approximation of the number of digits in an integral type.
 *
 * Parameters:
 *   itype - an intgeral type
 *           for example, DECIMALS(int) or DECIMALS(unsigned char)
 *
 * "Returns":
 *   the number of characters required to represent the type in text
 *
 * Comments:
 *   A blatant copy of the hard work of Peter Nilsson:
 *      http://groups.yahoo.com/group/cncppassist/message/13395
 *
 * Example Usage:
 *   char response [ DECIMALS(int) + 2 ]; // extra room for '\n' and '\0'
 *   if ( fgets(response, sizeof response, stdin) ) { /* ... */ }
 */
#define DECIMALS(itype) \
( sizeof(itype) * (CHAR_BIT * 12655UL) / 42039 + ((itype) -1 < 0) + 1 )

*Sort of -- I dressed it up with the "Example Usage" section. It was in a larger hunk of code that I lifted those two lines more or less directly.

My boss does his best to try to get me to comment everything first, and then write the code.

[Well, I think I've killed this to death already.]

[Narue]

That's a lot of commenting for (technically) one line of code. Let's look it over, because I think you went a little overboard:

/*******************************************************************************
 * Description:
 *   A compile-time approximation of the number of digits in an integral type.
 *

Cute border, but does it really add anything? There's no need to say that you're giving a description if the macro is commented well. But I'll get to that in a moment.

* Parameters:
 *   itype - an intgeral type
 *           for example, DECIMALS(int) or DECIMALS(unsigned char)
 *

Completely unnecessary. The description clearly states that DECIMALS works with an integral type, and the parameter is called *type, so it's not only safe to assume that itype is an integral type, it's obvious to any competent reader.

* "Returns":
 *   the number of characters required to represent the type in text
 *

Technically it doesn't return anything, it evaluates to something. ;) There's no need to include this either as the description practically screams what the result is.

* Comments:
 *   A blatant copy of the hard work of Peter Nilsson:
 *      http://groups.yahoo.com/group/cncppassist/message/13395
 *

This is only needed if the link adds anything important, or if there are copyright issues. I'll assume the code is public domain because copyright issues are annoying. ;)

* Example Usage:
 *   char response [ DECIMALS(int) + 2 ]; // extra room for '\n' and '\0'
 *   if ( fgets(response, sizeof response, stdin) ) { /* ... */ }
 */

I'm hesitant to bitch about this because example usage is a good thing. I would like to believe that readers would be able to figure out how to use the macro, and example code may limit creativity in how it's used.

#define DECIMALS(itype) \

DECIMALS isn't exactly the most intuitive name that could be used.

Tell me, what does your comment (and code) do that this doesn't (aside from take up space):

/* Approximation of the number of digits in an integral type */
#define DIGITS(type) \
( sizeof(type) * (CHAR_BIT * 12655UL) / 42039 + ((type) -1 < 0) + 1 )

[Dave Sinkula]

>That's a lot of commenting for (technically) one line of code. Let's look it over, because I think you went a little overboard:

Somewhat exaggerated, perhaps, but it the same argument for whitespace: "everyone else" always has too much or too little.

>Cute border, but does it really add anything?

For me, it does. I divvy things up into "hunks" and I find it easier to spot the beginning/end.

>There's no need to say that you're giving a description if the macro is commented well. But I'll get to that in a moment.

It follows a format used with functions for a consistent look and feel.

* Parameters:
 *   itype - an intgeral type
 *           for example, DECIMALS(int) or DECIMALS(unsigned char)
 *

>The description clearly states that DECIMALS works with an integral type, and the parameter is called *type, so it's not only safe to assume that itype is an integral type, it's obvious to any competent reader.

Just hammering home that you don't feed it an object like most C and C++ functions receive.

>Technically it doesn't return anything, it evaluates to something. ;)

Yes, thus the finger quotes.

>There's no need to include this either as the description practically screams what the result is.

Again, consistency. At least I've started dropping these "section" headers in functions returning void or receiving no parameters.

* Comments:
 *   A blatant copy of the hard work of Peter Nilsson:
 *      http://groups.yahoo.com/group/cncppassist/message/13395
 *

>This is only needed if the link adds anything important, or if there are copyright issues.

The important thing, I figured, was a better explanation of how it works as well as crediting the author.

>I would like to believe that readers would be able to figure out how to use the macro, and example code may limit creativity in how it's used.

Using it has already prompted questions on another forum we are familar with, so I don't know that the uncommented version or even a sparsely commented version is as good.

>DECIMALS isn't exactly the most intuitive name that could be used.

Since I was stealing it, I left it as is.

>Tell me, what does your comment (and code) do that this doesn't (aside from take up space):

/* Approximation of the number of digits in an integral type */
#define DIGITS(type) \
( sizeof(type) * (CHAR_BIT * 12655UL) / 42039 + ((type) -1 < 0) + 1 )

• It doesn't follow a consistant format (from which this example was taken). Though not a function, it is function-like and nontrivial, so I borrowed the function header format.
• It is not like sizeof that can be used with either an object or type. I found this most odd when I first toyed with it. So I figure the parts that messed with my head the most when I first saw something are the parts that may need special care for anyone who is not as familiar with such things. It is somewhat counterintuitive for C and C++ that the parameter must be an actual type.
• It doesn't provide a link to the explanation of the derivation of the magic numbers used, or any of the rest of Peter's more detailed explanation.

Sometimes redundancy is just redundant. But other times the rewording can help make the confusing clear. YMMV.

[EDIT]Also, the information is more detailed with the autocomplete whatever thingy.
[IMG]http://img148.exs.cx/img148/9608/decimals7pp.th.gif[/IMG] [IMG]http://img148.exs.cx/img148/8155/digits5gy.th.gif[/IMG]

[Narue]

Ahh, you're a breath of fresh air Dave. :) To be perfectly honest, I had mostly guessed your counter-arguments, but I wanted to make sure that you could defend your decisions adequately.

>It doesn't follow a consistant format
You don't want it to be consistent. Function macros are not functions, and if you start treating them as functions for consistency then you increase your chances of falling into preprocessor traps. If you want to be consistent then have a consistent commenting scheme for object macros, function macros, and functions all separate and easily distinguished.

>I found this most odd when I first toyed with it.
That's because you're comparing it with sizeof. Operators are on a whole different plane of existence from macros. ;)

>It doesn't provide a link to the explanation of the derivation of the magic numbers used
That's a good point, and why I added the qualifier that "if it adds anything important", which it probably does. I didn't follow the link.

[Dave Sinkula]

>I wanted to make sure that you could defend your decisions adequately.

I felt a grillin' coming -- you've seem to have been a little boxed up lately. [Perhaps even too restrained with our friend helloworld. :evil: :) ]

>You don't want it to be consistent. Function macros are not functions

Generally, even the function-like macros I use IRL are so simple comments are not really required. The complete list for the current project.

#define WDR()      __watchdog_reset()
#define CLI()      __disable_interrupt()
#define SEI()      __enable_interrupt()

#ifndef BIT
#define BIT(x) (1 << (x))
#endif

/* Compile-time array size calculation */
#define ARRAYSIZE(x)  (sizeof(x)/sizeof(*x))

The first three are actually under a compiler-specific conditional compilation. That last one seems to have one of those redundant comments. I guess that's what I get for commenting on the run. :rolleyes: [edit]Actually it seems to be only tagging along for this project -- it is not yet used anywhere.[/edit]

I chose the function-like bit for this case because the macro was more complicated. And I don't care to have too many different schemes -- I use two forms (each with the funky banner line): sections such as headers, variables, constants, definitions, types, plus others; and functions, which as we have seen list more than just a simple title as done by the sections.

>If you want to be consistent then have a consistent commenting scheme for object macros, function macros, and functions all separate and easily distinguished.

I'm open to suggestion. Do you have a preferred style (I walked right into that one, didn't I?)

[Fasola]

allow me to interject

this is all way over my head, but i WILL i repeat i WILL have my day :)

appreciate all the comments, even though it stopped being about me a long time ago

i think i'll read this discussion in its entirety thoroughly and catch up that way

because i really need to get up to speed

how long have you two been coding?

and was exactly is Macros? i remember having to disable or enable macros for a Excel Applications at work before. what is it?

[Narue]

>Do you have a preferred style
My preferred style is to let the code do the talking. ;)

[Narue]

>how long have you two been coding?
About nine years.

>and was exactly is Macros?
A macro is a preprocessing directive that textually replaces itself with the text defined by the macro:

#include <iostream>

using namespace std;

#define MACRO 5

int main()
{
  cout<< MACRO <<endl; // Prints 5
}

After preprocessing, the code looks something like this:

// Contents of iostream

using namespace std;

int main()
{
  cout<< 5 <<endl; // Prints 5
}

This is an object macro. You can also define macros that take arguments. They're called function macros:

#include <iostream>

using namespace std;

#define MACRO(x) (x * x)

int main()
{
  cout<< MACRO(5) <<endl; // Prints 25
}

After preprocessing, it becomes

// Contents of iostream

using namespace std;

int main()
{
  cout<< (5 * 5) <<endl; // Prints 25
}

[Dave Sinkula]

>Do you have a preferred style My preferred style is to let the code do the talking. ;)

Dang! Say, uh, I don't suppose I could get you to talk to my boss... :)

>how long have you two been coding?

Since 1995. But I did dabble on and off since somewhere in the 80's. My rebirth (discovered c.l.c., forums, etc.) was in about 2001.

[Fasola]

9 yrs? Since the 80's?

i don't feel so bad now :mrgreen:

i started in 1999 - 2000 and haven't coded since i think 2002

i really need a computer of my own :(

[Narue]

>Say, uh, I don't suppose I could get you to talk to my boss...
It's good to be the boss. ;)

[Fasola]

>how long have you two been coding? About nine years.

>and was exactly is Macros? A macro is a preprocessing directive that textually replaces itself with the text defined by the macro:

#include <iostream>

using namespace std;

#define MACRO 5

int main()
{
  cout<< MACRO <<endl; // Prints 5
}

After preprocessing, the code looks something like this:

// Contents of iostream

using namespace std;

int main()
{
  cout<< 5 <<endl; // Prints 5
}

This is an object macro. You can also define macros that take arguments. They're called function macros:

#include <iostream>

using namespace std;

#define MACRO(x) (x * x)

int main()
{
  cout<< MACRO(5) <<endl; // Prints 25
}

After preprocessing, it becomes

// Contents of iostream

using namespace std;

int main()
{
  cout<< (5 * 5) <<endl; // Prints 25
}

GREAT EXAMPLE, GOT IT ;)

THANKS

[server_crash]

New code --- Efficency

Modifying code -- improve efficency :mrgreen:

[Dave Sinkula]

New code --- Efficency

Modifying code -- improve efficency :mrgreen:

This made me look up to the list on my wall.Brian Kernighan's Programming Style Tips

Here is a summary of the very important programming style tips from Brian Kernighan's 1994 guest CS50 lecture.Say what you mean, simply and directly.
Use the ``telephone test'' for readability.
Write clearly - don't be too clever.
Don't use conditional expressions as a substitute for a logical expression.
Parenthesize to avoid ambiguity.
Each time you make a test, do something.
Follow each decision as closely as possible with its associated action.
Use the good features of a language; avoid the bad ones.
Capture regularity in control flow, irregularity in data.
Each module should do one thing well.
Make sure comments and code agree.
Don't just echo the code with comments - make every comment count.
Don't comment bad code - rewrite it.
Use symbolic constants for magic numbers.
Watch out for side effects and order of evaluation.
Macros are not functions.
Watch out for off-by-one errors.
Test programs at their boundaries.
Program defensively.
Make sure input cannot violate the limits of the program.
Make it right before you make it faster.
Keep it right when you make it faster.
Don't sacrifice clarity for small gains in ``efficiency.''
Don't stop with your first draft.
[From The Elements of Programming Style, Kernighan & Plauger, McGraw-Hill, 1978]Rob Pike's Rules Regarding Complexity

Most programs are too complicated - that is, more complex than they need to be to solve their problems efficiently. Why? Mostly it's because of bad design, but I will skip that issue here because it's a big one. But programs are often complicated at the microscopic level, and that is something I can address here.You can’t tell where a program is going to spend its time. Bottlenecks occur in surprising places, so don’t try to second guess and put in a speed hack until you’ve proven that’s where the bottleneck is.
Measure. Don’t tune for speed until you’ve measured, and even then don’t unless one part of the code overwhelms the rest.
Fancy algorithms are slow when n is small, and n is usually small. Fancy algorithms have big constants. Until you know that n is frequently going to be big, don’t get fancy. (Even if n does get big, use Rule 2 first.)
Fancy algorithms are buggier than simple ones, and they’re much harder to implement. Use simple algorithms as well as simple data structures.
Data dominates. If you’ve chosen the right data structures and organized things well, the algorithms will almost always be self-evident. Data structures, not algorithms, are central to programming.
There is no Rule 6.

[Narue]

>This made me look up to the list on my wall.
Don't do that, most people can't handle all thirty rules at once. ;)