Of course, sometimes you had to write a function that had to be called from more than one place (strange I know!!)
For this, the naming convention "pzzDDDD" was used where D was a digit from 0-9. "p" for procedure and "zz" because these functions didn't belong to any one place in the hierarchy.
We had a print out of the "pzz"s because just the number was hard to remember. But I can still remember a few of them:
* pzz0030 was for looking up account information from the database (but also for maintaining this information).
* pzz0031 for contracts
* pzz0241 I think was for looking up fees and commissions.
Most of the "functions" had lots of parameters so that they could do different things (modify, update, delete accounts etc.). This soon became unwieldy so eventually you had:
* pzz0241_a_setupcharges()
* pzz0241_c_cleanup()
or something. I forget the details for this last bit.
I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extraction of documentation and intellisense. I am no drone by any means, but this isn't so insane if you give it some thought.
There wasn't "the occasional pointless-looking artifact"; I would have been fine with that. 95% of all code comments merely mimicked the type signature. People were using Visual Studio plugins to autogenerate the "documentation". Pressing SHIFT+ALT+J (or something) would read the function name and type signature and regurgutate some XML doc matching it.
> allows extraction of documentation and intellisense.
These already give you type signature and function name. If intellisense already gives you "bool isValid", what possible gains do you get from an extra "boolean value indicating whether the value is valid"?
> I am no drone by any means, but this isn't so insane if you give it some thought.
Trust me, I have given it plenty of thought. Some conclusions from these thoughts:
- Code comments that merely mimic the type signature add nothing. Not for readability, not for intellisense, not for documentation extraction.
- They increase the signal-to-noise ratio of the code immensely, making it harder to read. Comments with actual useful information will now drown in the sea of drivel.
- Fuck it, I'm not working here anymore.
The main fallacy here is that More Process and More Rules can make bad programmers write good code.
Fair enough. I found that in a collaborative environment (people making and sharing code) the style guidelines had a net positive effect (and believe me, my first gut reaction was along the 'this is insane' lines). As process go, the degree of automation and strict automatic enforcement (and fixing) of rules felt lightweight after a bit.
We're neither of us going to convince the other, I just thought I'd add a datapoint. FWIW I now write Python and although PEP8 isn't as hard-line, I think it similarly does a lot of good.
>> Code comments that merely mimic the type signature add nothing. Not for readability, not for intellisense, not for documentation extraction.
Agreed. In fact, over time, they are likely to be not merely useless but harmful as the API signature evolves over time, unless the developer also updates the (pointless) comment.
If you're using a tool like Sandcastle to generate separate documentation, it won't produce decent output for elements that don't have XML comments. For that reason, while I also find those comments to be irritating I'm still in favor of a requirement that they be present for anything that's meant to be consumed by third parties.
Also, it sounds like some of the problem you're describing could have as much to do with people being slackers about the rule, than the rule itself. Someone should be taking charge of making sure these XML comments are useful, high-quality comments. There's almost always more information that should be provided beyond re-iterating the element's name. For example, the XML comments for a property named "IsValid" should reference some documentation of exactly what defines a valid state for that class. Numeric properties should very likely have notes about what unit denominates them. At the absolute least, make sure that every property's descriptive comment starts with "Gets", "Sets", or "Gets or sets".
Just to get in ahead of an obvious answer, let me also go ahead and say that if this is a situation where it's reasonable to tell users that they should just RTFS, then obviously this is a situation where there's not necessarily any need to require XML comments in the first place. But if you do need to require XML comments, you should also be requiring proper XML comments.
Intellisense is generated from the types, methods, fields, and properties (the API). If there is XML documentation it is added to Intellisense popup. If the documentation is auto-generated from the code structure then it will add nothing that is not already present in the Intellisense.
Sure. Like I said, there are some cases where the textual documentation adds nothing to the stuff it's derived from. And there are lots of cases where documentation is useful (I'm assuming you're not saying there should be no documentation). I think that it's worth having consistency of rules (with some redundancy) over patchy documentation. I'm not trying to convince anyone, just a datapoint that I don't think it's "insane".
The original point was that auto-generated documentation comments contain nothing that isn't already there in the public interface. Since it tends to look like
/**
* Foos the bar.
*
* @param bar The bar.
*/
public void fooBar(Bar bar) { ... }
The problem with this kind is that the compiler can no longer warn about a missing documentation comment because from its side all looks nice and well – except that there is zero information in that documentation.
My boss once did that to our entire codebase, adding auto-generated doc comments where there weren't any. Sure, my warning count reached a new low, but documentation quality suffered for months.
But why XML? IMO the doxygen / javadoc style of comments makes for much less pollution. XML is not a good format for text that is to be read by humans.
> To NEVER remove any code when making changes. We were told
> to comment all changes.
I'm afraid given this rule, I would abuse it horribly. My backspace key would no longer function and every typo I make would introduce a new set of /* */ comments. Every refactoring would have the old type, variable, line, function, or entire class commented out with the fixed code alongside it. Bonus points for interleaving the old code and replacement code.
I understand the rule, we have this rule in place with a caveat. The rule protects us from a few common events, first being that where some developers just love to tinker with code outside the scope of their project. The second is simply a bad design where the results affected other code in unexpected ways.
There have been a few times were code was reverted and having the code merely commented out saved time, time spent cut/pasting from archive. Even with a good CMS keeping commented out code can serve another purpose, knowing what was when and why. That way we can avoid the "well back in year X we had a rule" because we have the code readily accessible.
For large blocks (subroutines/procedures/etc) it is not uncommon to move the whole to the end of the source.
I've seen this mostly as workaround for broken source control systems, along with a change log at the top of each file. For example with ClearCase it can be a hell to find out preceding revisions of a file (the tools are slow and very user unfriendly), actions that are trivial with more modern systems.
I tend to agree more with coding guidelines that go exactly the other way: Do not leave around any commented out or dead code. It breaks the flow of reading the code and can cause confusion as to what is actually happening. If you need to refer to an old state of the code, just provide a commit id in your comment.
Most amusing I've seen was Java code that was rather over zealous about DRY and no-string-literals in code (i.e. all strings had to be define as constants).
public final static String COLON = ":";
public final static String SLASH = "/";
public final static String DOT = ".";
public final static String COM = "com";
[Apologies if this contains any Java syntax errors, I pretty much stopped using Java soon after this experience]
Also I've just realised that I'm really glad Java doesn't have a standard pre-processor - truly evil things would then have been possible <shudder>
The strangest coding standards were imposed when I was working at an AS/400 shop a dozen years ago.
No indentation allowed. Even though the modern compilers supported it, it looked ugly to veterans who had worked with fixed-format compilers for 30 years.
No comments in the code allowed. The function had to be entirely clear by looking at the code. Any code that needed comments for clarification was considered too 'clever' and 'obfuscated' for production.
No new language features allowed. IBM maintained languages and tools always acquire large amounts of feature bloat over the decades. Only a small subset of these features was 'white listed' by the CTO.
That's not necessarily bad advice - at least as a starting point. If you use descriptive variable/function names, then a huge amount of your commenting usually needs go away.
The big advantage is that people are rarely very good at updating comments - at which point they become at best useless and often downright misleading, Whereas most coders will hopefully at least consider renaming a function or a variable when it's no longer accurate.
Normally I'd tend to agree with you, but if the gp was using an AS/400, I bet their software was written in RPG.
Now, let's play a game. :) I'm going to Gist the example RPG program from Wikipedia, but with all the comments stripped out. Take a guess as to what it does:
My company's entire internal business infrastructure is written in, perhaps, millions of lines of this (commented, thankfully).
"Right," you may say, "but this is surely easy enough to read for someone who's used RPG for a while." Now consider that (afaik) RPG hasn't been taught in schools since the 70s, and that this entire format is alien to folks reared on Java. Even a poor comment in this environment is like suddenly stumbling across a line of semi-cogent English scribbled in the margins of the Necronomicon. Which is to say, it might just hold the insanity at bay for a while longer. :)
Footnote: the Wikipedia article mentions a "FREE" mode that makes writing RPG much more similar to modern languages (what an old hand here might call "freeform" languages, a.k.a. languages that aren't column-based). But I get the feeling that the gp's company would regard such notions as heresy.
I worked at a start-up whose engineering lead brought familiar coding style to a project that was inherited. We were imposed a combination of C89-esque and Microsoft kernel coding style on an Objective-C source code. Things like defining all variables at the beginning of the function definition in alphabetical order in CamelCase, having instance variables prefixed with the class abbreviation, and other inane rules. It went something like this:
Maybe someone knows of a solution but it would be great if SVN/version control was able to store a standard formatted version of source code and then depending on client/user preferences could reformat the file accordingly on checkout and then also be able to factor in / unformat when doing diffs/checkins. I feel like if it could work like this it would mitigate a lot the inevitable battles that take place over small things like formatting/etc. There are obviously things like variable names that it wouldnt be able to solve but at least nobody would be complaining about where Joe put his curly bracket. I guess you can do something similar with an SVN hook but its hard to get a seamless process.
What I've always found an intriguing idea is to store the abstract semantic graph of the program instead of (just) the text of the program in the revision control system. The source code could then be formatted / visualized in any way for the programmer while manipulating it. Kind of like a TeX, or CSS, but for source code. And I suppose it could also help with making sensible diffs, no longer need to be annoyed by addition of spaces / indentation / number of columns / etc.
"A language should be designed in terms of an abstract syntax and it should have, perhaps, several forms of concrete syntax: One which is easy to write and maybe quite abbreviated; another which is good to look at and maybe quite fancy, but after all, the computer is going to produce it; and another, which is easy to make computers manipulate."
This won't work, except for trivial codebases, I guess. Dean Whelton argued a similar thing once [1]. There are always things that resist automated formatting or that are downright destroyed when using it. I use Ctrl+Shift+F or Ctrl+E,D sparingly for that reason. Eclipse has a tendency to mangle Javadoc comments sometimes. Sometimes you're breaking a long method invocation or formula over multiple lines for readability and not exactly at the 80-char boundary, etc.
Of course, trivial things like braces on the same or next line or whitespace around operators are solvable that way, but in general, as long as source code is text (and it will remain that way for quite some time). What perpetuates this state is obviously that we have lots of tools that deal with text and very few that deal with more specialised content. In general I find this sad, though, as text is often neither easiest to work with nor most expressive, despite of what diehard Unix users say.
What would be really lovely in my eyes woul be a source control tool that actually understood its content and could say "order of parameters of that function was changed" or "method added", etc. It's sometimes astonishing how the pursuit of optimal diffs masks the intent of a change where an added method diff starts with the closing brace of the previous method, for example.
"It's sometimes astonishing how the pursuit of optimal diffs masks the intent of a change where an added method diff starts with the closing brace of the previous method, for example."
In Python you can get the whole return statement. Especially when adding a similar type of method, e.g.: Django view functions. Makes
I've found that experimenting with the various git diff algorithms helps out. IIRC there is an "-x patience" flag you can pass to git-diff and tools which use that, which spends more time to get "better" diffs.
Eclipse has pretty good code-formatting control for Java, quite customizable. It's very nice in that:
* you can elect to turn off formatting for sections of your code
* you can save/export your formatting convention in an XML file that looks like this: http://pastebin.com/fKjKRuZg
* you can import that code convention into new/other projects
* you can select any number of files or projects and choose to apply the formatting to the Java source
* the result is very readable
This might not tie in directly to your source control tool as is but would make taming and standardizing source from multiple developers a bit easier. As long as every contributor's code eventually is coerced into this form your own/central copy can easily be diff'ed across versions. Also, you could apply other conventions with other formatters for clients that see things differently.
I know a solution: Agree on the broad points of formatting - ie. tabs/spaces, where the braces generally go. Make engaging in formatting battles a firing offense, but listen to anyone who can make substantial arguments in favour of a practise.
Automatic reformatting is evil - sometimes codes is more readable if formatted in a particular way. Readability and maintainability always trumps adhering to rules.
Automatic reformatting is the only solution, because you want to be able to make unreadable code readable without conscious effort. My preferred policy would be something like:
1. There is an agreed autoformatting template, checked into version control.
2. It is always ok to format the lines you are working on however you like, with the understanding that other people may run the autoformatter on the file.
3. It is always ok to run the autoformatter on a file you are working on (autoformatters only really work at file granularity).
4. It is not ok to format code you are not working on.
I mostly agree, although I'd like to enhance the bit in point 3 and 4 about only ever reformatting code you're actually working on - meaning, you take responsibility for any code that your autoformatter changes is just as readable as before.
Changing the name of a constant on line three doesn't give you license to autoformat the rest of the file.
I think it does. Carefully maintained manual formatting takes too much programmer effort. If you open a file to actually work on, you should be permitted to hit the autoformat button without thinking, because then formatting becomes something you just don't think about. It's not as good as good manual formatting, but it's good enough, and frees up mental resources for more important things.
I'd say this depends on the project and the developers. In some projects reading code is done a lot more often (and by more people) than actually writing code, so then you might want to spend more time on e.g. formatting, documenting, etc..
I guess what Im saying is if you could have a tool that could compare 2 pieces of source code, be able to merge them, and maintain the formatting of each persons local copy it would be great. Its probably a pipe dream because your version control would have to have an intimate knowledge of the specs of any particular language used in the source code (nevermind the version of the language you are using)
Yes, for merging, that would be incredibly helpful.
But what I'm saying is that the formatting of a file may contain contextual clues that will help someone reading the code to understand what it does. Formatting isn't just chrome around the code.
Example: In Java, when writing a custom predicate to filter by foos that are bars, I prefer
filter(myList, new Predicate<Foo>() {
@Override public boolean apply(Foo foo) { return foo.isBar(); } });
to
filter(myList, new Predicate<Foo>() {
@Override
public boolean apply(Foo foo) {
return foo.isBar();
}
});
(filter is statically imported from Collections2 in Guava)
especially when there are multiple of them and they line up neatly underneath each other.
Any meaningful autoformatter would change the latter to the former, and in the process loose readability.
EDIT: Another example would be when using the builder pattern - getting those methods to line up to be neatly readable often takes some none-standard indentation.
Yeah, you'd likely need some other way to refer so a position in the code than the line number. Maybe an anchor (like html) or a path in the syntax tree.
These tools already exist: JavaScript tools like minfiers or CoffeeScript can generate source maps which map code lines from one format to code lines in another format.
The company must scale! Sysadmin and webdev must be split! Therefore all (junior, barely unix-aware) web developers must provide automated Freebsd-specific install, test, start and stop scripts in a custom and ill-considered package format with no inter-component runtime or instllation-time dependency support. For every project. Therefore the perlmonger in charge and sysadmin extraordinaire can automate their dabblings.
Needless to say, getting barely PHP capable people who'd heard of unix to automate dependency installation and maintenance on such a platform didn't work out well. Did I mention this was 2010?
In one project, I had to use camelCase and cargo-cult-Hungarian prefixes in table objects: tblTableName, sVarcharColumn, iIntegerColumn, vViewName and so on. I actaully surprised myself with just how deeply and viscerally I hated this convention. I could no longer easily convert column names into human-readable headings on reports; and the prefixes were just redundant, completely missing the point [1] of Hungarian Notation.
The strangest one was when I was a COBOL programmer in the mid 80's and was forced to learn and used the GOTO verb. Having learned COBOL JSP style I was unaware that goto even existed in COBOL until then.
There again same place made me retest a program I'd tested and was fully working as a full-stop was missing of a comment line.
Many answers show a common trend: absurd prefixing rules. They're not only useless, but also counterproductive, because they prevent the incremental searches that are present in so many parts of the development tools.
If you prefix every table name with "tbl", you can't search for them in the DB manager console, the IDE table listing, a directory list of the creation scripts, etc.
I suffered an extreme version of this: there was some prefix that was also the directory name. So the files were called "prefix/prefixBlah". Also the prefix was used as class name and the fields were also prefixed with it.
The result was that a reference could become "prefix/prefixBlah/prefixBlah.prefixDoh", an awful noise to signal rate.
I complained without success. That way was "a lot more orderly and tidy" <sigh>.
I was talking to someone today, and they commented:
"Good programmers eventually learn to misspell words like void or int so that they can name their variable names what they want to name them."
I of course told him that this was terrible advice, and would mess with the next person who had to maintain the code because you couldn't tell at a glance if a word was a keyword or a keyword mispelled. I asked him what language he was using.
FORTRAN.
Where did he work.
The United States Air Force.
For how long?
Six years.
When?
Before 2000.
Since he had more experience, he claimed I was de facto wrong.
I fought him on it some more.
He told me it was personal preference. I told him you'd have to make me do it.
It was at that moment I figured that someone, somewhere, had probably had to do this as part of a coding guideline.
But such things are quite annoying for automatic code generators, though, as they have to make sure that they won't ever emit an identifier that clashes with a keyword. The ability to just prepend @ in C# is quite helpful in that regard.
On a vaguely related note, there was a project kicking around a month or so ago to store editor-neutral code formatting specs in the project root. Can anyone remember what it was? My google-fu is failing.
None were strange. I agreed with all the coding standards I have been forced to follow. The key to not be annoyed by them is to not work at places enforcing stupid standards :)
In my first job as part-time programmer at a bank back in 89, we were developing a large system in C, pretty advanced stuff compared to the usual 'buy from IBM' approach at the time. The 'systems analyst' broke down the design into modules and functions for the entire system, and everything was named something like 'ABM10EI00405'. Yeah, those were the actual names we had to use for .c files and functions.
I've come to believe that coding standards always end up being either too simplistic to deal with every scenario or longer and just an inferior in-house implementation of Steve McConnell's "Code Complete". Either way you're wasting your time.
Style guides are ok though, so long as they're short and not enforced too bluntly.
Reality: Just try to understand the hierarchical relationship between 247 functions in a 10,000 line Material Requirements Planning module of an ERP system when every function name must be all alpha.
I think it is crazy. Especially today, when IDEs can show you the declaration of a variable or method while hovering over it, there is no need to encode the type of a variable into the name. Variable names need to be sensible to humans, the compiler doesn't do checking on them anyway: it's all too common for the type prefixes to become misleading when a program has been refactored and they don't match up anymore.
I'm not sure what you're referring to, but in all instances of Hungarian notation I've seen (especially in Windows programs) it was the data type (pointer to char, 8 bit int, 32 bit int etc) encoded and not "the nature of the thing".
I agree that adding the "nature of the thing being counted" makes sense, but then you don't have to call it Hungarian notation anymore, "number_of_apples" is just a sensible variable name...
Thanks for the explanation. The original idea was pretty good.
But I've only, ever, seen the corrupted variant in the wild. And coding standards that enforce it. Hence my annoyance.
Yeah, Hungarian Notation may have flowered in the Councils of Elrond, the mere sound of which would give men Knowledge, Wisdom and inflation-adjusted semi-annual raises, but out here on the edge of Mordor it's been horribly twisted into something only an Orc could love and look upon. If an Orc could love.
Likely because it tied into a data dictionary from a documentation system.
The tbl01 makes it unique (so you can have a users and someone else can have theirs too), the data dictionary then tells you what fields exist in that particular table and how those fields relate to other tables.
That is why only products made by engineers for themselves should be re-used (nginx, redis, etc.) and those been "managed" by idiots should be avoided.)
Over-management is much more common and much worse problem than over-engineering.)
One convention was that all "procedures" should be prefixed with a name indicating where they were in the call graph of the program.
So the main method was always:
The first function called by a_initialize had to be called "aa_", then "ab_" and so on: and so on.Of course, sometimes you had to write a function that had to be called from more than one place (strange I know!!)
For this, the naming convention "pzzDDDD" was used where D was a digit from 0-9. "p" for procedure and "zz" because these functions didn't belong to any one place in the hierarchy.
We had a print out of the "pzz"s because just the number was hard to remember. But I can still remember a few of them:
* pzz0030 was for looking up account information from the database (but also for maintaining this information).
* pzz0031 for contracts
* pzz0241 I think was for looking up fees and commissions.
Most of the "functions" had lots of parameters so that they could do different things (modify, update, delete accounts etc.). This soon became unwieldy so eventually you had:
* pzz0241_a_setupcharges()
* pzz0241_c_cleanup()
or something. I forget the details for this last bit.
This was in 1997.
Neat huh? ;-)