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 ...


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 ...


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

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. ...


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 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

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 ...


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

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 ...


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

This endpoint: api\Items Is not the same as this one: api\Items\1 Therefore, they can return different responses. As you have indicated, getting items may just return a list with just a few properties while getting an item by ID may return a heavier object. Avoid decriptive terms such as "small" and "large" in your api/endpoints if the endpoints are ...


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

I think when you see this kind of commenting, and I write this way myself occasionally, It's because the author is writing the spec out in the comments and then going through and implementing each comment. If we are challenged to write a coding standard which produces code which is understandable in terms of its required functionality rather than its ...


4

There's nothing which is as big as PHPDoc, but we're using airbnb, which already has over 2.000 stars and more than 350 forks on github, so it's used in a lot of projects.


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 ...


4

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". This obviously goes above and beyond documentation - this touches how the code is structured, ...


3

HTML 4.01 Strict Validation is one of my automated tests in my ATDD test suite. For us validation is important because of consistency of browser behavior. So if you don't need consistency of behavior across different browsers (and browser versions), then it's probably more of a nice-to-have. Driving consistency of behavior for all your pages makes the ...


3

I am going to go out on a limb and say that there are none, and even if there was one, it would be ignored because the programming community is too diverse and opinionated to all agree on something. That being said, the JavaDoc/Doxygen family is as close as we are likely to get. We might see a few large camps develop, but that's it.


3

It's very unclear to me what you mean with "standards", but there is for example the Java Language Specification which determines how a JVM should work and thus provides a guideline for people that want to write their own JVM implementation.


3

TL;DR: Use automated linting and a commit hook code reformatter. When I was doing Perl we decided to put a lint checker in our test suite, and a commit hook that automatically reformatted the code. We did this so that going forward we would not incur more technical debt from lack of code consistency and linting issues. We didn't want to pay the time cost ...


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