Saturday, April 13, 2013

Block separated commenting or not?

I recently received the following anonymous comment on my most recent post:

"Your blog is hard to read due to the difficulty in separating text from r code. Why not separate the two instead of comments throughout the code?"

I have been writing a response and decided to post it as an independent post since many people may have similar concerns who read the blog.

Let's first define what I think of as the alternative style that most blogs use.  Please don't take offense all of you fantastic bloggers out there.  I think this format as with all blog formats is extremely useful.  I just think that there are reasons why other formats might also be desirable.

------------------------------------------------------------------------------------
Typical posts look this way:

Explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation.

Explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation.

Explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation.

code block:
> some useful code
> some useful code
> some useful code
> some useful code
> some useful code

Explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation explanation.

----------------------------------------------------------------------------------

My Reasons for doing things the way I do them: such as in Tit for Tat - Axelrod tournament style competitive simulation

1. I believe this is a matter of style.  Personally I find blogs in which there are paragraphs of comments followed by small amounts of code difficult to read.  I would like to figure out how to get my syntax color coded.  However, I have not figured out a way to do this which does not result in code boxes and the like.

2. The format of the blog makes it very easy for someone to take an entire post and copy it right into a code editor.  From that point, they can run the code piece by piece.  This helps to address the lack of syntax color coding.  In whatever favorite editor people may have they can see my code color coded.

3. I was uncertain about this style initially as well. However, many more people have visited my blog than I had originally ever hoped.  Upwards of 100,000 page views at this point.  Why mess with what seems to work?

4. There is always a trade-off between quantity and quality.  Some might be bothered by this but I have aimed to put out more quantity than quality.  I don't mean to degrade my work but often there are spelling errors in posts and other minor errors that might bother people.  However, this is not my job and so I must squeeze in posts when I have the time and inclination.  I experimented initially with separating code from comments but found the structure much more time consuming.

5. I post things to my blog not to give people free code that they can use for their own purposes but to show people how to code various things.  From what I have seen, when code is fully commented ex-ante then it is either very small amounts of code such as a 1 to 5 line command or function.  Or it is using a very large amount of code that users are not expected to read but only copy and paste.  I am not interested in coding solutions to problems for others but rather in showing people how to become competent coders.

6. I think separating the code body from the comments inherently limits the ability of a blogger to post complex or lengthy code.  Some have suggested that they don't want complex or lengthy code in posts. That is fine but there are many other blogs out there which already fulfill these requirements and I don't see a reason to change what I am doing.

Finally, I would like to say that I have no problem with the way other people structure their blogs.  It works for them and this works for me.  Having a diversity of options available to satisfy the tastes of many different people is a great thing.

4 comments:

  1. Well... I have to say, I do share some of that anonymous person's comment. Writing your article as comments to your code (leading #) is fine, but what really kills it is the lack of visual contrast between code and text. You should definitely use different colors and fonts. Also, using a monospaced font like courrier for your code is a must.

    ReplyDelete
    Replies
    1. Okay, I have gone courier. Let's see what people think.

      As for color coding. Does anybody have an automated script that I can use to recognize automatically syntax markers such as lines that start with # or *?

      Delete
    2. I switched from courier. I can't stand trying to read monotype. It is too ugly for me.

      Delete
  2. I like your commenting style. I usually copy your code into an editor and play around with it. Not having to look something up in the blog entry but to have all comments right at the code suits me well.

    In addition, I find blog entries that consist of code only stylistically charming.

    ReplyDelete