Tags:
coding_style1Add my vote for this tag dev_essential1Add my vote for this tag create new tag
, view all tags

Discussions on Coding Standards

I've always found the variables "$web" and "$theWeb" inherently confusing, and it seems that was the problem in the OopsRenameAccessDeniedHasMainWeb bug too. What is the difference?

-- MartinCleaver - 10 Oct 2004

Blows my mind as well. At first I thought it was that $theWeb always referred to values taken from the query, but there is no consistency. My conclusion is that $web, $webName and $theWeb are used interchangeably. Bound to happen when you have many authors. The problem is that there are often global variables with the same name, so you don't get a non-existence error.

-- CrawfordCurrie - 10 Oct 2004

The naming convention is based on ideas of the Wikipedia:Hungarian_notation. The Hungarian Notation is mainly used in C, C++ and Java to give a meaningful name to identifiers. For example, sName indicates a variable of type string, dSize a double integer, pdSize a pointer to a double integer, etc.

There is not much value in Perl to name variables by type. However it helps to see if a Perl variable is global, local or parameter based. See our CodingStandards on this subject.

-- PeterThoeny - 11 Oct 2004

Oh, I see. But Hungarian notation is not used consistently, which is what confused me. I'd have expected to see (examples)

  • $iVariable - integer
  • $sVariable - string
  • $pVariable - reference to an object
  • $giVariable - global integer variable
  • $ssVariable package private (static) string variable
As you say, in an environment where polymorphic types are rife, the value of Hungarian seems limited. That's why it's largely been abandoned in OO languages (what is sVar? A C string? A C++ string object? A typo?), except by a few strongholds like szMicroSoft that is! But at least we understand the convention now, thanks.

-- CrawfordCurrie - 11 Oct 2004

I'm all for standards that are useful, intuitive and followed but our the* prefix is confusing and seemingly error-prone.

How about a global S&R to change it to param*?

-- MartinCleaver - 11 Oct 2004

What would be fine with me, although more in a "refactor as you go" style.

$param* is somewhat long. Since it is used all over the place it does not need to be verbose. Would this work?

  • globals: $globFooBar (highlight 'em so they will be reduced)
  • locals: $fooBar
  • locals from parameters: $parFooBar

-- PeterThoeny - 12 Oct 2004

Please don't. I personally find Hungarian notation reduces the readability of code, and perl is already unreadable enough.

-- CrawfordCurrie - 12 Oct 2004

I agree with CC's comment about readbability. Its the wrong argument.

The issue is about scope and reference and consistency. Hungarian, Polish or Turko-Aramaic wont' address that, its to do with design and architectecture.

Elsewhere "object" models of Wikis get discussed, and the idea of a "Wiki instance" and a "topic instance" come forward. Dealing with object, handing around the object context, avoidn all this parameter list name. If you are in the context of the topic object then the web is the one that the topic refers to. To refer to any other one you have to be more explicit and fully specify it.

I must admit I'm tired of wainting for fully O-O Perl. The thing we have in 5.x is rather kludgy and not very transparent. I like Perl, it just wish it did O-O properly like Ruby. I've done that "context thing" in Ruby; its sweet and clear and clean. Perhaps I shold be thinking of re-writing TWiki in Ruby?

-- AntonAylward - 13 Oct 2004

I really wouldn't want to see Hungarian notation as it looks quite ugly - $theWeb is not particularly easy to read and more of the same wouldn't help, though $parWeb is not too bad. To attract more developers, it helps if the naming convention is not too complex, as now.

-- RichardDonkin - 13 Oct 2004

How about we move to named parameters as standard?

This is really simple:

Instead of

   my ($theThis, $theNeverUsed, $theThat, $dontForget, $theOrder) = @_;
   print $theThat, $theThis, $dontForget, $theOrder;
use:
   my %p = @_;
   print $p{that}, $p{this}, $p{dontForget}, $p{order};

This also has the advantage that if we ever get to Perl 6: it aligns with how this passes parameters and is consistent with the pass hash method of the stinky ModPerlize patch.

Note that this affects the calling routine as well, but we can probably engineer a solution to this. At a minimum I would like us to agree that it should be the standard moving forward.

-- MartinCleaver - 15 Oct 2004

No way, Jose. Far too much recoding for my tastes. Far too vulnerable to abuse,. Far too inefficient. AFAIK it is not any more consistent with OO perl than the existing method.

  • Deleted my "OO TWiki" comment above. -- MC

I find this whole named-parameter approach really horrible to deal with when I'm using an API. Fixed parameter lists act as an automatic aide memoire and mnemonic cue. With named parameters you have to be constantly referring back to the documentation to work out how it works - e.g. LWP, which is horrible that way.

-- CrawfordCurrie - 15 Oct 2004

http://perlmonks.thepen.com/353826.html details a validation process - of course you ought check your required parameters are present, TWiki suffers from a lack of parameter checking.

-- MartinCleaver - 15 Oct 2004

sub save ( $web, $topic, $text, $saveCmd, $attachment, $dontLogSave, $doUnlock, $dontNotify, $theComment, $forceDate ) what's your mnemonic for remembering that one? hehe!

-- WillNorris - 15 Oct 2004

your inefficiency claims are unsupported and unfounded, especially when viewed in a larger context (ie, passing around what are essentially struct pointers could be faster than passing around scores of parameters)

fnCall( { topic => "CodingStandardsDiscussions", text => "New Text", dontNotify => 1 } )

save( $thisTopic )

it could also help clean up the lines of noise at the topic of each function call, instead of converting function parameters into local variables.

-- WillNorris - 15 Oct 2004

I bow, as always, to the superior knowledge of the perl guru ;-), even though the inefficiency in my mind is the typing of all those parameter names on every call. But I still don't like it, for the memory reason I gave above. But if you really want to go through and change all the code, don't let me stop you. I'm sure you will document thoroughly as you go.

Oh, and yes, many functions in twiki have obscene parameter lists. I hate this practice of silently ignoring excess parameters and letting them drift into undef as well. I recently got caught out by the "ignore permissions" parameter to TWiki::Func::readTopicText because I copy-pasted the code from somewhere else that didn't have the parameter, so I didn't know I had to set it.

Bah humbug.

-- CrawfordCurrie - 15 Oct 2004

Helpful comparisons deleted.

-- MartinCleaver - 16 Oct 2004

Bugs:Item5301 and Michael's rather sensible dislike of tabs in source code (and of course the CodingStandards ) suggets to me that we should start applying perltidy to our code base.

I would prefer to just use the default settings of perltidy, and to apply that to all code, but I presume some people may have stronger opinions on it.

One thing I would like to make sure of, is that there are no functional changes to the code whenever there is a formatting change, and thus, It makes sense to define an automated tool to make the formatting happen, just like with unit tests.

-- SvenDowideit - 31 Jan 2008

Hey coding is a handcraft. I'd prefer people would write nice looking code right away. This way I know they are awake while they hack along wink

The impact of properly formatted code on code quality should not be underestimated. And it surely does not stop at formating code. Let alone naming variables and methods and their inner coherence...

If you delegate part of that to an auto-formater, some of this is simply lost. Besides, code formatters are stupid, too stupid, and I always found myself at reformatting the code in a way "it made more sense".

-- MichaelDaum - 31 Jan 2008

Formatting is just the tip of the iceberg, yes. But having consistent formatting rules does help code readability, and is a good place to start. Other coding rules - such as avoiding the use of obscure perl idioms - is the next step.

-- CrawfordCurrie - 31 Jan 2008

Processes that rely on human opinion - especially of the reformatting the code in a way "it made more sense" sort, do not tend to scale well. Instead, it results in some 'styles' being denegrated, for any number of reasons, be they inexperience, or brilliance.

I find many of the idoms and styles used in TWiki code stupid too, but often they are the result of many different individuals, all fearing to impose their style on others.

Thus, I prefer to have a trivially enforceable correct style, and that requires a code formatter.

perltidy in my opinion, can be considered to be written by better perl programmers than ourselves, who have spent more time than we care to developing a style.

Thus i suggest we use this resource and learn from it.

-- SvenDowideit - 31 Jan 2008

Coding standards and guidelines are most important. A piece of well written code is so much easier to maintain. However I find that a developer better acquire the skills to read the most commonly used coding standards out there cause one day or another it will come your way.

I think having any kind of automated tool doing thousands of code changes in our source control system is madness unless you have 100% test coverage.

-- StephaneLenclud - 01 Feb 2008

I have bad experience from applying autoformatting tools and not having done it from day 1.

People that provide patches will be using untidy versions and it patching then gets broken because of white space problems or you have to spend time inspecting fuzz warnings.

Another problem is if the tidy is not run the same time and way between all branches incl current experimental branches which we have at least two of. Merging back code becomes more difficult when code is tidied.

I support the use of coding standards and try to follow the best I can myself and also gets irritated by tabs etc.

But please watch out before applying perltidy on all code and please do not run it on all code at once.

-- KennethLavrsen - 01 Feb 2008

Merge issues due to formatting changes are going to happen, irrespective of wether we use an automated too or not. I re-brought up the suggestion specifically because Michael quite reasonably reformatted the Users code in MAIN (I had avoided it specifically because we've been in code freeze for so long).

Thing is, that a tool that formats, will always do so in the same way, so in the longer term, it significantly reduces confusion, reduces the number of times there are merge failures due to white space, and completely removes the non-functional changes due to personal preferences, or forgotten reformats.

in short, is seems to me that the reasons you give, support using a tool to reformat the codebase.

-- SvenDowideit - 05 Feb 2008

Edit | Attach | Watch | Print version | History: r21 < r20 < r19 < r18 < r17 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r21 - 2008-02-05 - SvenDowideit
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.