The Stack Overflow podcast is back! Listen to an interview with our new CEO.
171

Michael Durrant's answer is IMHO not bad, but it is not literally answering the question (as he admitted by himself), so I'll try to give an answer which does: I also understand that comments should explain why the code does what it does, not how. Given all this is it even possible to write good coding standards that capture this idea? Obviously you ...


151

Major anti-pattern leading to poor quality code with less clarity btw readers, the title was originally "comment every line of code?" and you can imagine the instinctive reaction of many of us, myself included. I later retitled to the longer more accurate title. At first, reading your question I thought, yuch duplicate stuff in comments , but ok, maybe if ...


32

Let's think about the specifics here for a moment, using examples you've cited: ntfs - Proprietary to Microsoft. Anyone who is not Microsoft cannot use this, therefore would have to use/create something different. Now, if you are Microsoft, you want to use this over FAT because of the issues of the next bullet point. fat32 - Not sufficiently modern. The ...


24

What are the key aspects and contents of a good coding standards document? Being supported by tools which enable automated checking of the code. If I know that I can't commit to version control any piece of code which doesn't match some rules, I would be encouraged to follow those rules in my code. If, on the other hand, some fellow programmer have written ...


24

Short answer: One size does not fit all. There are trade-offs. For example if you want a journaled FS, you pay (efficiency, complexity, etc.) for it but get something out of it. Some don't feel the need for a journaled FS and don't want to pay for it, some do. Same with other "features" of the FS.


23

I don't think a coding standards document is the place to specify what is already common sense. The purpose of a coding standard is to guarantee consistence (and avoid arguments) about issues where reasonable people might disagree and there is no single obvious right answer, e.g. naming conventions, indentation etc. Such commenting as in your example is ...


19

It is not possible. What you are essentially trying to do is nearly to mechanize good judgment. When writing critical software such as for life supporting medical systems, huge amounts of checklists and whatnot are virtually inevitable. Not only do even smart people make mistakes, a lot of the software for these devices is written by people that aren't very ...


18

Given that: The two "big name" implementors, Netflix and Ebay, abandoned it a couple of years ago and excitement for OData pretty much died with their departure, OData is a RESTful way of exposing a query mechanism through an abstraction layer. Such abstractions are now widely seen as leaky abstractions, which are a clear anti-pattern, I'd suggest OData is ...


14

There can't ever be one "best" of anything because there are so many opinions about what "best" is. The decision is specific to the needs and limitations of the user. Designs are always based on their ability to fit within constraints. A basic mobile phone needs to store a few hundred contacts, text message history, and a few small apps. Does its filesystem ...


14

The C++ standards committee is full of smart people that are fully aware of the amount of existing code and the consequences of introducing new keywords. One of the aims of the committee is to keep as much existing code as possible working unchanged and that certainly plays a large role when deciding to add new keywords and how to name those keywords. To ...


14

Update My response in quotes for emphasis: It is my belief the answer that states the comments should not be addressed in Coding Standards and then lists a set of defensive questions to fight it, is the only correct answer. The issue here is that a Coding Standard is just that, a Standard. Extremely subjective ideas should not be in a Coding ...


12

Validation will always be important, but during times of transition from one standard to another it's very difficult to pull off. It's especially hard when the standard isn't even finalized and agreed upon yet. So while validation is important, business is more important and simply won't wait for validation. So there will inevitably be some indefinite ...


12

There are two different things you allude to when you talk about comments. They're not the same, and the distinction is important. Documentation tells you about the outward-facing bits of a piece of code - its interface. Typically tooling will allow you to read them in a 'standalone' fashion, i.e. you're not looking at the underlying code at the same time. ...


11

Too much depends on what you want to optimize. Consider FAT for a moment: its support for long file names is kludgy (to put it nicely), and searching through files in a directory is linear so it gets slow very quickly if a directory contains a lot of files. At the same time, it has a bare minimum of metadata to raw write speed is very good, and since it's ...


10

You can't codify a commenting standard, because you can't know what the important comment will be in advance. But you still want to make sure the code is commented correctly, since this is life critical code. The solution is to have a standard for the code review - require that code review comments on understandability. This won't guarantee that it won't ...


9

The main issue with Standard Architectural models are they that only work on standard systems. The problem with real world enterprise environments are that they are ALWAYS different. In turn, the standards would end up being so vague that you might as well be better off without any.


9

Just a quick question, but why are there so many file systems still competing and in use today? (ntfs, fat32, ext3(ffs), etc) It seems that file system designers could agree upon the best aspects of each type of system and implement a "best" filesystem, no? Let's suppose that there weren't tradeoffs, and file system designers did implement a "best" ...


9

The answer to this was ANSI SQL. Although initial adoption was hard, especially for databases like Oracle, many of them now allow the ANSI standard. For example Oracle started allowing that format in 9i (see http://allthingsoracle.com/ansi-sql/) Also - PostgreSQL prides itself in standards compliance. Its SQL implementation strongly conforms to the ANSI-...


9

Comment every line of code? No. The purpose of the others rules you talk about is precisely to avoid that. Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment. If you comment whole code which is self-explanatory, you double the amount of reading with out giving any ...


9

The question: Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42". Comments should not seek to educate the reader on the language. A reader should ...


8

C++0x now is named C++11. Since C++ never was compatible with C, i doubt that C++11 will be. As for compatibility with C++ 98, have a look at the ISO standard for C++11.


8

HTML validation isn't a huge deal deal for a few reasons, that don't really have anything to do with HTML 5. It doesn't really mean anything other than some group says this is right, if you did everything else right a validator can't check. HTML isn't source code for a vast majority of projects, other things are generating HTML and you have limited power ...


8

The first important thing to note is that a coding standards document is not about right and wrong. It's not about good and bad or which method is better. A coding standards document's purpose is to make sure that all code is designed, written and laid out the same to make it easier for a developer to switch from one persons work to another without the ...


8

It’s questionable whether there is any other organization similar to the W3C; it really depends on your definition for similarity. There are standards organizations in the strict sense (W3C is not a standards organization but an industry consortium) that define standards for programming languages, most importantly ISO, working together with the IEC in this ...


6

I was going through this process multiple times. And the most successful (although bumpy anyway) was approach was to take "Coding Standards" document from well known company and modify it to fit your needs. For example, I just found this one: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf Anyway, keep your flame-thrower handy. Cheers,


6

There are no standards organizations specifically for programming languages. ANSI (American National Standards Institute), ISO (International Standards Organization)(I think) exist to write standards. When someone wants to put a standard together for something, they put a pitch together and present it to the organization. If the organization agrees that ...


5

Introducing new language features and extensions, most of the time, require new language keywords or syntax changes. In addition, its essential to name these keywords for their intended purposes so as to help programmers memorize the new features. Fortunately, for that purpose, new language version/standards contain a list of code-breaking changes that you ...


5

gets was invented at a time when there were no millions of malicious hackers trying to steal your financial data via the internet. There was no internet to speak of. People didn't put their entire personal lives on computers. Only highly paid specialists were ever supposed to have access to digital computers at all. Briefly, the threat-countermeasure trade-...


4

As is so often the case in computing the answer is (a) because of historical circumstance and the need to maintain backwards compatibility and (b) because some methods are better suited to some tasks than others. On (a) you need to remember that the "Winchester drive" - I am just about old enough to remember them being called that - (what the rest of the ...


4

I hate most standards documents as they usually try to sweat the small stuff and ignore the bigger picture. For example, nearly all of them will say how to name variables or place brackets. This is pure style and does little to really help a group of devs code correctly. They ignore stuff like directory structure and code layout. I've seen standards ...


Only top voted, non community-wiki answers of a minimum length are eligible