Stop me if you've heard this before... [modified]

[Zac Howland]

led mike wrote:

Use case Analysis will NOT depict every method that will be written in the code.

I don't believe I ever said it would. I said (and you quoted) "intentions for features and modules". If you really need EVERY method documented to understand what it does, your code isn't being written in a readable manner. If you follow proper guidelines for writing functions, they will have a single objective and will be short enough that even a novice programmer would be able to look at it and have a good idea of what is going on.

If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac

[led mike]

Zac Howland wrote:

your code isn't being written in a readable manner.

Now we have circled back to the original discussion about self-documenting code through names will NOT depict aspects like pre-conditions etc.

Zac Howland wrote:

If you follow proper guidelines for writing functions, they will have a single objective and will be short enough that even a novice programmer would be able to look at it and have a good idea of what is going on.

Sorry, but I disagree. Someone may understand that int x = input << 5; will shift the value of "input" 5 bits left and store it in "x" but they will have no idea "why" the system needed to do that. This type of situation is fundamental in software development. I can't even believe I am having an argument about it.

led mike

[Zac Howland]

led mike wrote:

Now we have circled back to the original discussion about self-documenting code through names will NOT depict aspects like pre-conditions etc.

:sigh: I'm not even going to get back into that discussion again ...

led mike wrote:

Sorry, but I disagree. Someone may understand that int x = input << 5; will shift the value of "input" 5 bits left and store it in "x" but they will have no idea "why" the system needed to do that. This type of situation is fundamental in software development. I can't even believe I am having an argument about it.

Out of the context of the function, that line means nothing. However, if you had a function (simple silly example):

int multiply_by_32(int input)
{
	return input << 5;
}

It should be clear. About the only thing you might want to comment there is why you used bitshifts instead of multiplying, but if it is in an area of code that needs to be highly optimized, that should also be self-explanatory (and should be mentioned at the top of the source file). Perhaps I should clarify why I disagree with documenting code too much after it has been written so you get an understanding of why it is a pain:

// Complex.h
class Complex
{
public:						// public members
	Complex();				// constructs Complex
	Complex(const Complex& c);		// copy-constructs Complex
	~Complex();				// destructs Complex

	Complex& operator= (const Complex& c);	// copy-assigns Complex

	/*
		I declared the following functions as friends so that implicit
		casting can be used on the left side.  I found out that if you
		make them member functions, only the right side of the operator
		can be implicitly casted.
	*/
	friend Complex operator+ (const Complex& l, const Complex& r);	// adds 2 Complex numbers
	friend Complex operator- (const Complex& l, const Complex& r);	// subtracts 2 Complex numbers
	friend Complex operator* (const Complex& l, const Complex& r);	// multiplies 2 Complex numbers
private:					// private members
	double _real;				// stores real part of number
	double _imaginary;			// stores imaginary part of number
};

/****************************************************\
 * Adds 2 Complex numbers
 * Input: 2 valid complex numbers
 * Returns: valid complex number
\****************************************************/
Complex operator+ (const Complex& l, const Complex& r)
{
	Complex ret;