style guide

[fred rosenberger]

ok, i have some dumb questions... i'm starting the whole process, and am having a few... issues

1) multi-line comments
the style guide says nothing (that i can find) on what is proper format. the one place it HAS a multiline comment, under Self-Documenting Code, it's using the /** and */ javadoc format. should we use this for all multi-line comments?

2) extra parameters
the assignment says

Purpose: To learn how to follow the style guide, how to get the argument from the command line, how to use variables, how to concatenate strings, how to use a loop effectively, and how to output to the screen (standard out).

Write a program that will read in a name from the command line and write it out 100 times.

In other words, I want to type

java Hundred Gertrude

and see (image)

now, what are we supposed to do if the user gives an extra parameter? For example,

java Hundred Gertrude fred

should the program fail? should it ignore fred? or should it print "Gertrude fred" a hundred times? i can see the arguments for each case. anybody else wonder? or am i just over-thinking the problem?

[Adam Price]

I found that the degree to which I was expected to anticipate and code for a foolish user was not entirely consistent.

On Hundred, my (accepted) solution would have completely ignored any arguments beyond the first one.

[Joyce Lee]

I had this similar issue in the past while working on the assignments. I guess I went a bit overboard when checking the user's input.

To keep thing simple and consistent, I wonder if the students can safely assume a user always enters the correct input. With this assumption, the program does not even have to check the number of command-line arguments being entered. The instructor's solution I received included this checking:

// Is it acceptable to skip this checking?
if ( args.length == 1 )

[ April 11, 2006: Message edited by: Joyce Lee ]

[Jim Yingst]

Regarding javadoc-style comments, I don't think it would ever make sense to use this style inside a method, for example. Use /** */ only when making actual JavaDoc comments in places that the javadoc tool will look for them (immediately before classes, fields, constructors, or methods). Elsewhere you can use /* */ or // - either is allowed by the style guide. (Dunno if you get additional feedback on this under nitpicking though.) Note that if your code is self-documenting, you should need few such comments anyway.
[ April 11, 2006: Message edited by: Jim Yingst ]

[paul wheaton]

"... what are we supposed to do if the user ..."

What if it rains? What if the world ends? What if the user types in nothing? What if the user's first name is 400 characters long? What if the user types in just one character? What if the user types in a number? What if the user types in just punctuation? What if the user types in some character beyond ASCII 127? What if the name isn't a real word? What if it snows?

The (feeble) point I'm trying to make here is that once you start to travel down the "what if" road, it can turn a mosquito program into a 900 pound gorilla.

Focus on the business requirements. Do the simplest thing that could possibly work. If you see a "what if" case that will happen more than 20% of the time and you can handle it easily with almost no code change, then sure, take care of that case. Part of what the nitpicker is doing is acting as your customer. Often, business needs are not reflected in the specification, but you may get feedback later from your customer. This is the way the business world works for geeks like us these days.

As for comments: typically, less is better. If you have a powerful need for comments, you can usually replace that need with better identifiers or by moving some code to a well named method. I find that about 90% of the time I feel the need to put in a comment, some slight shifting of the code eliminates that need. But there are still times when I think the best thing to do is to leave a comment.

[Carol Murphy]

Honestly Fred, I believe the thing to remember for these assignments is not to look for any hidden landmines. Keep the code as simple as possible, and only solve the problem as given. If the nitpicker wants more, she'll tell you.
I'm reading this thread in the San Mateo County Courthouse jury meeting room in Redwood City, and I had to laugh out loud, cause I've been there. There's no dumb questions, or I would have asked one already! Everyone's staring at me. Gotta go now.

[fred rosenberger]

Paul,

isn't part of my job, as a developer, to think of things the user didn't? I always thought that the MORE dialog i have with the customer, the better. it's much easier for me to talk to them about problems as i find them, rather than say "here's what you asked for, but here's a list of things you DIDN'T think of that will be a problem".

then it takes them a week or month or year for them to review it, and say "oh, yeah. that WILL be a problem - go back and fix it". i then have to remember what i was doing (and yes, all that about self-documenting code comes in here). it's much easier to ask the questions at the time they come up. at that moment in time is when i best understand the problem and can best think of the solutions. or, it is with the least amount of additional work.

Maybe i am overthinking these problems. maybe i should just shut up and eat a piece of pie (or a whole pie). Maybe i just love to argue (my wife will tell you that's the case). But, maybe i am just trying to do the best i can. [and maybe ALL are true].

and now, i'll go have a donut.
[ April 12, 2006: Message edited by: fred rosenberger ]

[paul wheaton]

There's no dumb questions

Do I like pie?
[ April 13, 2006: Message edited by: Carol Murphy ]

[paul wheaton]

isn't part of my job, as a developer, to think of things the user didn't?

Your job, as a developer, is to meet the business needs of the organization.

The business needs of nearly every organization is to make money.

So, yes! Think of things that the user didn't. Think of things that the stakeholders didn't. Think of things that your boss didn't. And that your boss's boss didn't. BUT!!! this road can easily consume all of your time. To the point that the amount of benefit that you give to the company is not worth your salary.

I always thought that the MORE dialog i have with the customer, the better.

The best amount of dialog is not too much and not too little. In most cases, it is too little. As a professional, you will attempt to use techniques to get the most information without wasting time. Sometimes that means developing something and then getting negative feedback.

then it takes them a week or month or year for them to review it, and say "oh, yeah. that WILL be a problem - go back and fix it". i then have to remember what i was doing

True.

This is why these companies have two or three times more engineers than they need. If they had their act together, they wouldn't need to keep re-doing stuff. Frankly, companies that don't have their act together makes it so that more of us get more work! While this is not in the best interests of the company, this level of disorganization is beyond what we can control.

One thing that we can do is be agile. With good OO techniques and lots of code re-use, we should be able to easily slide into big changes.

Maybe i just love to argue

I think you have a passion to understand. A valuable attribute in any corporate monkey.

[Marilyn de Queiroz]

Or the customer will say (months later), I didn't need that, but this other thing isn't working the way I expected it to.

[Carol Murphy]

Originally posted by Paul Wheaton:
[QB]

Do I like pie?

QB]

I stand corrected.