FAQ update

[Duthomhas]

Yet another update on the FAQ.

I've begun working on the Beginner's / Homework section.

http://www.cplusplus.com/faq/beginners/

Completed items

Education
http://www.cplusplus.com/faq/beginners/books/
http://www.cplusplus.com/faq/beginners/tutors/

Headers and Source Files
http://www.cplusplus.com/faq/compiling/files/#headers
http://www.cplusplus.com/faq/beginners/multiple-sources/

Technical Issues
http://www.cplusplus.com/faq/beginners/null/


You'll notice the penultimate link is actually a link to a topic in the Compiling / Linking section of the FAQ

http://www.cplusplus.com/faq/compiling/

Everything you need to know about source code files
http://www.cplusplus.com/faq/compiling/files/

Anything you think is unreadable, needs clarification, or incorrect?

Thanks again for your time!

Dang it's tough to switch between bbcode and html!

[3hM2Nwbp]

One thing: +1 for linking to a license in source files rather than pasting a 100-line legalese block at the top of each and every file. (Should be a bolded point in 'conventions' imho.) I'll have more time to read over everything later tonight. Looks good at a glance though. No overly-complex jargon that would deter beginners.

[Albatross]

Lovely work so far!

It would be nice if in the compiling section you covered more modern build systems than autoconf. Just a recommendation, though.

-Albatross

[Duthomhas]

@Luc Lieber
Good point. I'll add a blurb about that.

@Albatross
Feel free to submit material. Do you still have edit permissions on the FAQ?
(If not, just PM me what you want and I'll put it in.)

I'm kind of dreading writing anything about build systems at all, especially autoconf. (My own build systems are usually fairly primitive -- a couple of system-specific makefiles. So I've got a bit of learning to do for that section.)


Right now I'm finishing up the (dreaded) FAQ on pointers vs references and arguments. I think I've been fair to both sides of the issue, and will post the updates soon.

[Lowest0ne]

I can't find a link to the faq anywhere on this site. Is this just me?

[BHX]

It isn't 100% done. You wouldn't sell a car if it was only partially done or a house for that matter. Same way you don't link to an FAQ that is only a fraction done.

[Albatross]

I don't think I ever had edit permissions for the FAQ, though I'd be thrilled to contribute to it. If you'd like, I could write something up about qmake. It's a generally good build system IMO, even with its strong ties to Qt.

And yeah, writing stuff about autoconf or even cmake will be tricky. I'm not remotely familiar enough with either to feel comfortable enough with them (especially autoconf, does anyone even use M4 for anything else anymore?) to write about them.

-Albatross

[Computergeek01]

I really like how much more detail you are going into with this, it is much more then you see on most sites.

The following comments are just my two cents they are not meant to be criticisms.

_{Duoas said:}

I'm kind of dreading writing anything about build systems at all, especially autoconf.

I'd like to point out that, as useful as they are, they are not a feature of the language; I'd say deprioritze that idea. No one would call the FAQ incomplete if you decide to drop it entirely and post a separate article though.

This entry could use some expansion:
http://www.cplusplus.com/faq/compiling/files/#projects
I know that this isn't meant to be an all inclusive RFC on project types. But mentioning that a driver is a (highly?) specialized form of a library and that a service is a specialized kind of executable would be cool. To me these terms are recognizable enough even for a new user that they deserve to be mentioned. These should be added as examples in that last hedging sentence in that section and that sentence should be a real paragraph.

I'd personally reword this part of that same paragraph:

They come in two basic flavors ...

to say something like

Libraries are incorporated into projects in one of two ways...

Otherwise it just feels like you're leaving it open for some jerk to come along and say "Duh, what about debug vs release versions? What about multi-thread safe vs. single thread versions...etc" and it isn't worth enumerating all of them.

EDIT: Could someone please link me to the thread that made this entry necessary?: http://www.cplusplus.com/faq/beginners/null/
Even if we assume that we have an imaginary case where input validation isn't possible, are we just trying to be nice to the people who think that you should never throw and handle an std::domain_error? Assigning a value of -3 to a bool does not make the bool invalid, it makes you a bone head.

[Duthomhas]

Re: build systems
As part of a C/C++ FAQ, I think they are appropriate. This site isn't just about the language itself. If it were, that would be a pretty severe restriction.

IMHO, the FAQ should include all common issues encountered when learning C and C++ -- including the getting-started basics of various build systems. Granted, such things can be mostly links to relevant sites and a simple example.

But they should answer the common questions that go something like, "Help! I don't understand Makefiles!"

Re: qmake
I like Qt's build system. I'll add a section for it. (And anything else I get, like cmake.)

Re: specialized project types
Thanks! Done!
http://www.cplusplus.com/faq/compiling/files/#projects

Re: NULL for non-pointers
http://www.cplusplus.com/forum/beginner/56713/ Null integer?
http://www.cplusplus.com/forum/general/102211/ Is null and space are same?
http://www.cplusplus.com/forum/general/44832/ String NULL?
http://www.cplusplus.com/forum/general/46508/ How to declare a varibale as null

All these are variations on the same problem, and the questions are come quite regularly. (Which makes me think I need to add another section to explain some of them specifically.)

Thanks for the feedback!

[Duthomhas]

Update. Added NULL string/whatever section.
http://www.cplusplus.com/faq/beginners/null-string/

[Duthomhas]

Update. The ever-contentious pointers and references FAQs. Behold!

http://www.cplusplus.com/faq/beginners/pointers-and-references
http://www.cplusplus.com/faq/beginners/call-by

I was debating adding links to the following (contentions) threads, but right now I've decided against it:

http://www.cplusplus.com/forum/general/35312/ Parameter Passing
http://www.cplusplus.com/forum/lounge/62708/ FAQ: What is call-by... (the precursor to the call-by FAQ).

Grey Wolf's information has been invaluable to making the FAQ on it. His original FAQ was directly responsible for the basic structure and some of the wording in the call-by-foo FAQ.

Also invaluable were JL Borges's comments here http://www.cplusplus.com/forum/general/139756/
(You can find them in the "Read the Standard!" point of view.)


So, fire away. Any egregious errors? Did I make any technical errors?

(For example, Grey Wolf said "The address of the argument z is used to make a reference" -- which is not technically correct. It may be how a reference is implemented when the reference is really a pointer underneath... but it is not the only way to make a reference, nor is the actual underneath way of making a reference relevant.

I'm not picking on Grey Wolf, BTW. I'm just pointing it out so you can see what kind of errors I'm looking for in my own work.)


Phew. Now to go do something easy. Like rocket science.

[z05DSL3A]

Duoas wrote:

I'm not picking on Grey Wolf

Glad to hear it. :0)

Duoas wrote:

For example, Grey Wolf said "The address of the argument z is used to make a reference"

When I was talking about 'make a reference' I was referring to the construction of the reference not how the reference is 'transferred' to the function, so I was basically saying that the address of z is used as the initialiser of c. Is that not so?

(it's late and I have to get up for work in four hours)

[Duthomhas]

Not always. (It is only true in the case where the reference is implemented as a pointer underneath.)

[z05DSL3A]

Okay, so maybe I haven't thought about this for a while.

A reference is initialised with an l-value, yes?

An l-value is an expression that resolves to an object in memory? An l-value has a storage address that are programmatically accessible, meaning that they are variables or dereferenced references to a memory location? An address?

Irrespective of how the reference is implemented, I fail to see how you can reference an object in memory without its address. Maybe you can explain?

______________________________________________

Duoas wrote:

Just so you know, “pass-by-pointer” is a not-made-up term, used by smart, technical people in the industry (like here). So if anyone ever gives you grief over it, tell them to get over it and move on.

If I were paranoid, I might take that as a dig at me. If you want to believe that passing a pointer by value is somehow special enough to warrant an new name who am I to stop you.

[Duthomhas]

A reference can only be made to an object which has an address, yes, but the mechanics of making a reference don't necessarily have anything to do with taking its address.

Also, I've made no dig at you. If you want to consider pass-by-pointer a new, made-up term that's your issue. It has existed for ages, and I've conveniently linked to a very old, big, and prominent company that uses it "(like here)".

(The dig, if any is to be taken, was more at one of the idiots over at codeguru who self-importantly proclaimed that "pass-by-pointer" doesn't exist. I wouldn't care, except that in one of the threads here on the forum someone at one point linked to his nonsense during our arguments.)

But as the FAQ says, it isn't worth arguing the issue. I've already hashed the reasons and mechanics in the FAQ. That the term exists really is incontrovertible. You may not like it. You may not find it in your favorite standard or in your favorite author's papers... but that doesn't prove anything about the term except your distaste for it.

 Duoas also wrote, in the paragraph penultimate to the one you quoted:

This does nothing to dispel the disagreements about what to call this method of passing arguments, but it should clear up what exactly is going on.

If you really don't think that it explains what is meant by "pass-by-pointer", explain why and what you would do to fix it. Computergeek01's post above is an excellent example criticism.

Otherwise, it's time to move on, okay?

[z05DSL3A]

Duoas,

I am (attempting) being light hearted here. I don't think you are having a dig at me. While (I think I) understand what people mean by “pass-by-pointer”, doesn't tally with my understanding of Call (pass) by value and call (pass) by reference (i.e. Evaluation strategy). Now I don't have anything to say on that front about the FAQ but I will say that the tone of that section, to me at least, comes across that you think people that don't agree with “pass-by-pointer” are wrong and idiots.


As for the other thing:

but the mechanics of making a reference don't necessarily have anything to do with taking its address.

I would still like you to explain how you can make a reference without the address of what you are referencing.

[cire]

A reference is initialised with an l-value, yes?

Yes and no. A non-const l-value reference must be initialized with an l-value (which, in this case might be simplified to "something with a name".) A const l-value reference may be initialized with an r-value (which, in some cases, extends the life of the temporary.)

And, while it is true that we must be able to take an l-value's address, if we do not there is nothing to keep a compiler from storing it in, say, a register, in which case the reference will not be implemented in terms of a pointer.

Conceptually, a reference is just an alias to whatever object it is initialized with and sometimes it is exactly that in practice, as well.

[z05DSL3A]

A const l-value reference...

I wasn't talking about a const l-value reference.

cire wrote:

And, while it is true that we must be able to take an l-value's address, if we do not there is nothing to keep a compiler from storing it in, say, a register, in which case the reference will not be implemented in terms of a pointer.

Storing what in a register?

[htirwin]

The

Everything you need to know about files.

title is misleading. At the least, "Everything" should be changed to "Some".

[cire]

Storing what in a register?

What is referenced.

In the following, how are the references implemented?

#include <iostream>

int main()
{
    int a = 4;

    {
        int& a_ = a;
        std::cout << a_ + a_ << '\n';
    }

    {
        // capture by reference
        auto double_a = [&]{ a *= 2; };
        double_a();
    }

    std::cout << a << '\n';
}

The machine code generate for the above is exactly the same as the machine code generated for the following:

#include <iostream>

int main()
{
    std::cout << 8 << '\n' ;
    std::cout << 8 << '\n' ;
}

If we're required to implement an l-value as something that resides in memory, and a reference as a pointer to that memory, how is this possible?

Compilers are not required to do either of those things.

Yes, this is a simplistic example, but it illustrates the point. Especially when dealing with inline and parameterized code, it becomes very likely a reference is just treated as an alias, and has no underlying representation at all in the generated assembly.