7

Personally, I have a severe aversion to code that I have to scroll sideways to see. I quite often edit peoples' questions and answers just to format the code to prevent this. I'd like us to have some guidance in the faq about how we'd like to see code formatted. This would help the authors, and it would probably lower the "permission to improve" barrier for people who just want to make the site a better place.

How many people aren't aware that you can get a line to break by hitting Enter? Is it just that people paste without formatting?

On SO, Mr. P got his editing badges for adding language identifiers to coding snippets. I think C# gets detected pretty well, as does XML/XSLT, but maybe it's interesting to have a pointer to some guidance on how to do this correctly by hand.

Beyond this, there are some common coding errors which are perpetuated by people learning from bad examples in sites like this. My own pet peeve in this regard is inappropriate as casts in C# code. I suspect there was some primordial templating example that had this problem, and we've been plagued by it ever since. Fixing this has a higher permission barrier than simple formatting, but it will be a general help to the community if we try our best to make sure at least that people don't learn bad practices here.

Of course, context is everything, and we need also to foster the notion that for example, commonly used using statements can be assumed, etc.

So - would some carefully crafted coding guidelines be a good thing? Other than my examples, what would you include?

4
  • 2
    I wanted to edit your question to correct the capitalization of "As" and to put it in back ticks, but that's apparently not very meta. #embraceyourinnermrp
    – Frank van Puffelen
    May 9, 2013 at 23:55
  • Assuming we get good answers to this question I would suggest recasting it question slightly as ‘What are the guidelines I should follow when posting code samples?’ and we can tag it with the FAQ tag.
    – Glenn Stevens
    May 11, 2013 at 5:54
  • @GlennStevens Only problem there is that this was begun as a discussion question, and people have responded in that vein. I think once we have achieved consensus, there will remain the task of distilling the results down to a FAQ format.
    – Dominic Cronin
    May 11, 2013 at 6:44
  • You are of course correct as I am realizing as I write an answer to your question. It should be easy enough to write a FAQ format question once we have consensus.
    – Glenn Stevens
    May 11, 2013 at 6:48

3 Answers 3

Reset to default
3

We have plenty of ways to encourage clean, readable code including edits, comments, and voting. Those who care the most will fix the biggest issues.

I'd rather not enforce a strict guideline but here are some tips, tricks, and practices I find useful (or keep forgetting), especially for Markdown Formatting on Stack Exchange sites.

Markdown

  • CTRL+L to start a link except in comments.
  • Wrapping a keyboard key with kbd adds some nice styling (e.g. <kbd>CTRL</kbd>)
  • formatting is done with [tag:tag-name]
  • Bold (**Bold**) and italics (*italics*) can help emphasis points (CTRL+B or I)
  • I keep referring to "How do I format my code blocks" on the proper syntax codes, basically it's <!-- language: lang-or-tag-here --> followed by an empty space then code.

Code

  • Sometime "standard" conventions like 3 or 4 spaces makes it hard to scroll--sometimes we have to resort to 2 spaces. Maybe having indents line up is more important?
  • For HTML, we should probably break at the start of an attirbute. Maybe line up with the containing node or maybe previous attribute?
<tag attribute1="value1"
     attribute2="value2" />

I'm not sure on any other guidelines, ideally each example is consistent within itself. :-) In terms of coding conventions and errors, I think this is another territory.

A Rant?

I think your "as" cast is worthy of a blog post and/or comments on where it comes up.

Reading between the lines, I'm guessing you're thinking in the context of "Tridion programming" we probably know what the objects are and can be sure the page we're referencing is really a Page.

So your preferred approach might be:

Page page = new Page(ItsReallyAPage);

StackExchange is for asking, answering, and learning. We should encourage readable (and safe-to-follow) code, but it shouldn't be a barrier to entry. I welcome "ugly code" in good questions because we can improve from there.

10
  • Yes - we should "welcome ugly code", but our guidelines should then encourage us to improve it.
    – Dominic Cronin
    May 9, 2013 at 21:42
  • Want to see if Frank van Puffelen's busy these days? :-)
    – Alvin Reyes
    May 9, 2013 at 21:45
  • I'm quite sure I already wrote a pretty good explanation of (Page)identifiableObject vs identifiableObject as Page on SO. Feel free to copy it from there (as if you need my permission to copy CC content). But don't expect miracles. Somehow there is a myth surrounding those as casts, similar to how the persistent rumor that using var makes your code slower. On that last one: it doesn't.
    – Frank van Puffelen
    May 9, 2013 at 23:58
  • @AlvinReyes I think you have awoken the van Puffelen. He is making edits faster than I can review them tonight.
    – Glenn Stevens
    May 10, 2013 at 0:16
  • @FrankvanPuffelen do you think it is a myth around as casts being slower or is it just a bad habit people have picked up due to syntaxes of other languages they may have worked in/with? You've got me wondering now how many people use resharper or one of the resharper competitors when they are writing their c# code (and what % of the people who are actually pay attention to what it says.)
    – Glenn Stevens
    May 10, 2013 at 0:22
  • 1
    What Puf said was that there was also a myth about var making your code slower. Regarding as casts, in fact they are marginally quicker than the equivalent code using is would be, but that's not the point. The problem is that people are using the as operator for general purpose casting, which is a mistake. When the type is known to you at the time of coding, you should use an ordinary cast. If you don't know whether the cast will succeed or not, it sometimes makes sense to use as and then check for null. Using as without a null check is almost certainly wrong.
    – Dominic Cronin
    May 10, 2013 at 13:21
  • 1
    +1 on that last bit: don't use an as is you're not doing a null check on the result. There is indeed a performance difference between hard casts and as casts. But anything where you hit a database or web service will affect you so much, that any performance difference the cast makes becomes irrelevant. Productivity lost from an as-without-a-null-check is unfortunately not irrelevant.
    – Frank van Puffelen
    May 10, 2013 at 16:49
  • @DominicCronin so we just make it a requirement everyone read blogs.msdn.com/b/ericlippert/archive/2009/10/08/… before they can post any code samples containing any type of cast right?
    – Glenn Stevens
    May 11, 2013 at 6:31
  • @GlennStevens #NotSureIfYou'reJoking, but the point of a guideline in our context is that it helps both original authors and those who are trying to improve the posts of others. Ideally the original posters will be motivated to follow the guidelines, but if they don't it's not the end of the story.
    – Dominic Cronin
    May 11, 2013 at 6:50
  • @DominicCronin definitely joking.
    – Glenn Stevens
    May 11, 2013 at 7:44
3

While I agree with the fact that we should place something like code guidelines in the FAQ, I myself am totally not bothered with code fragments that contain scroll bars.

I do try to make my code samples usually short enough so it doesn't scroll at all, but certainly the horizontal scroll bar is not something I will put much effort in to prevent.

Probably related to how I like to view code, as long as the most important part is visible, the bits more to the right can be hidden behind the 'fold'. I have the same in my editors, I never have them wrap my code, for me it's more readable when there is a scroll bar and lines are not wrapped.

Then taking Alvin's answer into account, I think some of those tips we should add to our FAQ. The big question would be where I think, also considering our FAQ are currently still very much standard because we are still in beta.

2
  • 3
    One of the first lessons I learned as a junior programmer was that if you allow code to be hidden past your right margin, "that's where the bugs will hide". It's a lesson that's served me well in the quarter century since then. All your code is important, and the likelihood that the code at the left is more important than the code at the right is vanishingly small. Of course, over time this practice becomes engrained as an aesthetic, but I could also make a reasoned case as to why one should be able to read code samples on a Q&A site without scrolling in two axes.
    – Dominic Cronin
    May 10, 2013 at 13:28
  • Bart, even for SE sites that have graduated the FAQ page that is linked to in the header and footer is pretty locked down. Basically you get to change the 'what questions can I ask here' section of the page (see chat.stackexchange.com/transcript/message/8230891#8230891) Generally the way to make our own 'custom' FAQs are to post a question here on Meta and have one of the moderators tag it with the 'FAQ' tag. If we settle on a good answer to this question it might be a good candidate for the first meta post to receive the 'FAQ' tag.
    – Glenn Stevens
    May 11, 2013 at 5:27
2

I think some carefully crafted code formating guidelines would be a good thing. It may be such guidelines are not ever explicitly seen by many members of the community but they would go a long way to informing the actions taken by the more active community members. If we are consistent in following such guidelines that would in turn provide the wider community with implicit examples of what they should do when including code samples in a question or answer.

Like Dominic I am also not fond of having to scroll horizontally to read code samples (or log file snippets for that matter) and think when possible it is a good thing encourage people to format code snippets so community users do not have to scroll sideways to see the whole snippet.

I am also going to add this to my internal list of things to look at when I edit a question or answer as I think this is the answer that prompted Dominic to post the formatting portion of his question and I had missed the horizontal scrolling when I edited the same answer to resolve other formatting issues just prior to his edit.

Regarding syntax highlighting, where appropriate we have configured tags with a default code language to use for the syntax highlighting of questions using that tag. For instance will result in the lang-xml formatter being used on any code samples in that question (well, sort of as there might be other tags configured with different code languages applied to the same question.)

This issue here is many of our tags, as an example, can result in samples from any of a number of languages. In those cases or when different tags applied to a question have different code languages, prettify uses its default syntax highlighting rules.

In cases where the syntax highlighting looks 'off' we can and should encourage posters to apply one of the following language identifies to the sample:

  • lang-none
  • lang-default
  • lang-bsh
  • lang-c
  • lang-cpp
  • lang-cs
  • lang-csh
  • lang-css
  • lang-hs
  • lang-html
  • lang-java
  • lang-js
  • lang-lisp
  • lang-lua
  • lang-ml
  • lang-perl
  • lang-php
  • lang-py
  • lang-proto
  • lang-rb
  • lang-scala
  • lang-sh
  • lang-sql
  • lang-vb
  • lang-xml

For snippets posted with common coding issues (or un-common coding issues for that matter) I would say it is always acceptable to edit them if they are posted in answers. I think this gets a little less clear if we are talking about a code snippet in a question as in that case it could be a contributing factor in the problem the OP is experiencing.

In all cases I also think it is acceptable to call out the issue in a comment on the question or answer. For example, on SQL questions posted on SO if the OP’s sample shows dynamically constructed SQL which is directly using user input I often see comments about the danger of SQL injection attacks.

It would seem to make sense to attach a similar comment regarding inappropriate as casts when you see them. In fact I would say it would make sense to edit an answer with an inappropriate as cast AND leave a comment mentioning this and the reason why the as cast was inappropriate and maybe a link to a relevent source that goes into more detail such as Eric Lippert's post 'What's the difference between "as" and "cast" operators?'.

1
  • Or if we have a faq section with more detailed links on a given subject, we could link to that.
    – Dominic Cronin
    May 11, 2013 at 9:46

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .