Documenting Software

I sometimes get amazed on how easier it gets to write the software given that I have its documentation written down.

Now that I am writing this stuff, it looks obvious that it is true, but back when I was struggling to implement a HTML utilities library for myself without its documentation, writting one prior to writting its source code made everything much easier.

I think this is related to having a precise software specification prior to its implementaiton process.

Obviously, in most cases, it is not even possible to document the whole software before having it, but it turns out that a complete and flawless documentation before hand isn’t needed. It is also pointless. Software design will change during the implementation process. However, you’ll still benefit from having a clear image of what you want to create.

In talking to some people at irc.freenode.com, it was somewhat common to have people starting to develop something using what is called OOP features, such as C++/Java classes. But, later they would just go back to some simpler language such as Python, Perl or Shell Script, sometimes, even C (I still, rarely, write some command line applications in C). Many GNU programmers tend to do pretty much everything in either C or some Lisp dialect (mainly emacs lisp).

Sometimes, your initial idea of what the software is going to need is not right. Some other times, you want to use a programming technique just because you think it is the better one (many people has that belief for OOP), or just because you like it (that is me for functional programming).

If, in the middle of the implementation process, you decide to change some interface, or some other piece of design, then things can get messier since the new design and the old design may confuse you (this just happened to me, by the way).

You may be tempted to believe that the design changes are small, and you’d be able to have two clear separated images of the older and the newer design, but it ends up being a very error prone situation. I suggest writing down all versions of the software design, as small documentation documents, as you go along with the implementation process.

Some documents out there, and people, suggest that you should design the whole software before hand, and just then implement it. I don’t agree with that idea. It looks too idealistic, and it’d make the whole software development process much slower. Sometimes, it is just better to just get some code written to see how things will be run by a computer.

An example of that is the discussion of bottom up versus top down design. I’ve heard people saying (very few) say that top down design is worthless. But my own experience says that top down design is very efficient for finding out how to do create your bottom up design, which is essential.

It is very hard to guess before hand what is the language you should build so that the implementation process of a software specification becomes natural. One way to get the feeling for which is this language is to actually start writing the software in top down design. Separate the major parts, and, as you write the software, you’ll feel the need for the layer of abstractions that would be very convenient to be had so to write the program.

In the beginning of On Lisp, this “process” is explained: how writting a software should give you the feeling “Gee, it really would be good to have SUCH AND SUCH feature in here.”, or “What I really need is THIS FEATURE.”. I don’t believe you can get this kind of insight without actually try to write the software.

There is a series of videos on JavaScript, by Douglas Crockford. The first one of the series is a speech he gives telling part of the story of computers and software. In that video, he told that functions, at first, were good for performance (space-wise), since your program text could be smaller given that it would have a given set of instructions repeated many times in it. After that, functions became means for modularity.

But later, people started to use functions in a different way. He tells that people started to think like “Which are the functions I have to write so that implementing my software becomes easier?”, which is the nature of bottom up design. And the only actual way, that I am aware of, to effectively answer that question is to try to write the software, and see how the base language gets in your way during the implementation process.

I think I got my point across. This post is getting pretty big. Bye now =).

Linking, loading and Chicken’s libraries, modules and deployment system

I’ve wrote a tutorial on the topic in this post’s title.

This tutorial is pretty much the result of me struggling to understand how I can use chicken for “real world” development.

I believe it is worth reading. Here is a link to it.

The guide is not complete yet. Mainly, how to use the deployment options for chicken-install needs some tweaking. I will wait until I get some more experience with Chicken to finish the tutorial.

Functional Currying in Scheme

Back when I was taking a look at Haskell, I saw that the language supports functional currying automatically: if you call a function, not providing all the arguments it requires, what you get is another function that can be called later, that takes the missing arguments, and does the job of the original function as if all the arguments were given all at once in a complete direct call. In other programming languages, if you call a function not giving all the needed arguments, you get an error. As in Scheme.

However, in Scheme, there is a very easy and simple way to implement functional currying; like the one I saw in Haskell.

(define (curry proc . args)
  (lambda x
    (apply proc (append args x))))

There isn’t much to talk about this, but you can, as I’m still doing, keep staring at it and see how simple it is.

Using this procedure, you can do currying in scheme. It seems that there is a srfi that implements currying with a macro called cut, but I’m unaware of it.

You might want to apply curry giving sequential, but not starting, arguments: giving arguments second, third and fourth for example; and then, the return function will take all the missing arguments and make the first given argument, as the procedure given to it in the first place’s first argument; the second argument would become the procedure’s fifth argument, etc.

Here is curry-middle, which does that.

(define (curry-middle proc start . args)
  (define (list-until l n)
    (if (zero? n)
        '()
        (cons (car l) (list-until (cdr l) (sub1 n)))))
  (lambda x
    (apply proc (append (list-until x start) args (list-tail x start)))))

Curry-middle is also simple, and is also small. It’d be a one liner if I knew some built-in function that could replace list-until.

I didn’t test those functions but their ideas are ok, and they seem to work. The first one (i.e. curry); I can’t see how it’d fail; but the second one may have some flaw I’m not seeing.

I’m Back

Well. I left this blog some time ago (actually, long ago), but I’m back now.

If you’re an old reader reading this, I gotta tell you that the approach of the blog will be different. I’m no longer interested in psychology, advertising and related stuff. I’m back to programming, and gaming, which were the things I liked before even getting interested in the stuff I used to talk about here.

Jazz Music; Please, Help Me People

I was listening to some stuff by Frank Zappa on YouTube and found this video.

I’ve found that very great. Amazing!

If you know any composer, band or anything that plays that style, please leave a comment to me with suggestions.

Apparent risk and actual risk, by Seth Godin

I’m here just to recommend a post I think everyone should read.

Apparent risk and actual risk

Is it really necessary to think?

I was watching this video on YouTube that is a speech of a man talking about design. Design in the sense of creating models, but not in the sense of graphical models.

He was showing examples of very dumb beings (such as cows, sheep, ants, …) that successfully survived and evolved without sophisticated thinking. They were dumb and yet survived.

And then he said a brilliant thing. Which was, They aren’t smart and don’t have to. The design is there, in the nature, to take care of its elements..

Now, stop and think for a while. How smart is that? I had such a big “aha!” when I’ve heard that.

This post’s title is a bit misleading. I’m not suggest you to stop thinking and let nature take care of everything. But it is fascinating the fact that whatever created nature, consciously or not, made a design that would take care of itself without its elements having to think (or without them having to do complicated thinking).

We, humans, can think very well, but we are a huge exception because if we are the most capable (in terms of thinking), then the second place is way below us. So, following the general rule, which doesn’t include us, it’s possible to create a design that take care of everything and no element of it needs to do any kind of complicated thinking (only basic thoughts for adaptation).

One can say that us, humans, don’t do any kind of complicated thinking too and that we only adapt so that we survive (which many people believe is the truth). So, even including us, the design takes care of its owner without requiring it to do anything more complex than adaptation (e.g. nature’s design takes care of nature).

Regardless of all my conclusions being right or wrong, …

… Let’s Getting practical

One can apply that to his/her life. Some things we do have patterns that can be spotted by very simple analysis.

If we can see the pattern and then build a design that will take care of everything, we can save the time and effort of thinking about that think and move on to take care of more important things that we don’t know any pattern to them.

Note: I’ve written this post in a hurry to not lose the “aha”, so it may be confusing for now. I’ll review it later one.

Adding to, improving and tweaking things

I’ve just came up with this:

If you want to tweak something, then remember that most tweaks you can add, if used incorrectly, can be counter productive and decrease its effectiveness.

There is a theory that says if you add a reason why someone should do something, they are more likely to do it. Which makes sense. We tend to do things better and more often when we know why we do it.

But here is something. If you don’t have a good enough reason, why would you give one?

Go take a bath!

Can be way better than:

Go take a bath because you need to wake up early tomorrow.

And surely better than:

Go take a bath because every child is supposed to take a bath at 8pm.

Sometimes, it is not obvious that we are screwing things by tweaking them. The reason theory example is just one of the several examples anyone can easily think of.

Bottom line is don’t tweak if you don’t know how to.

“If you want to know why something is wrong, then you need to know what it would be like if this thing was in its perfect state.”

The title says everything.

If you want to know why something is wrong, then you need to know what it would be like if this thing was in its perfect state.

This type of thought fascinates me because I see so many people trying to find what is wrong with something but without having a systematic way of thinking so that they can solve the problem. This quote relates to this because it gives you a way to start thinking about things that are wrong.

By the way, that is a great way of developing software. You can start with a model of a function in its perfect state; then write some code that is surely wrong; then start applying this kind of thinking to start fixing the function to make it fit the model.

NOTE: I’m using functions as examples because I’m used to that. You can do that with anything, obviously.

NOTE 2: I’ve seen that quote in a Biology documentary. Sadly I don’t know who is the guy that said it.

User Generated Content – What Is It For?

I was talking to my brother today. He has just read my post on facts about how people write reviews and there I show that many people don’t know what they’re talking about when they review a product. Other people go to a review page, see those crazy reviews and get the wrong impression about the product. That is what I believe is happening to some extent.

If you further read that post, which is very long, but useful, you can kind of conclude that you should not trust that religiously in user generated content.

What I’m going to bring in to this post is an issue that can be considered totally nonsense and useless, but I really think it’s worth to be analyzed for a while.

If you cannot trust in said to be serious user generated content, such as products reviews, what are they for? The reason why people read them is to clarify their thoughts, but since people can easily get confused by them, why are they for?

Of course every piece of existing content can confuse people and many do, but confusion happens much more frequently with user generated content and not with academic generated content, company generated content or serious news company generated content (I pretty much consider poor, which is what most are, news website normal user generated content websites).

If you take into consideration that you cannot trust anything (which can be argued to be true) and not trust anything, you don’t move forward with your life basically. Which is pretty bad. So, we have to trust something and make some decisions based on that. Most people are choosing to trust in normal user generated content without contesting instead of doing further research to see what is really true.

Are user generated content for guiding people who follow any or some advice without questioning?

When I was talking to my brother, he told me that he have already used reviews to help in his thoughts (he didn’t say if he used reviews extensively or just to have some general and not well formed ideas). By making the extended analysis I showed him that user generated reviews are not trustworthy. And that leads me to something relevant to this, which are priorities.

People have priorities. What I need now is different from what you need now. What I am doing now is different from what you’re doing now. Based on our current situation, we tend to prioritize different things. As a results of that we tend to be more analytical to some things than to others. For example, I’m more analytical to ads and sales related stuff now, but my brother is probably more analytical towards algorithms related stuff.

A worrying is just another “pain” in our lives. Adding another priority (e.g. being analytical towards every user generated content out there) would add a huge worrying for us, so we just avoid it. Maybe priorities answer why we believe in user generated content so easily. We just don’t want to analyze them and see if they’re right because that is too painful.

In my post I refer to in the beginning of this post, people review a book I’ve already read. In the past, reading that book, understanding it and getting to be aware of it and its content were my priorities. Not because I wanted to read reviews and see if they were right or not in the future, but because of something else, but the specific reason is not important here. The fact is that the priority I was with resulted in an awareness that allowed me to spot something wrong in all the 1 start reviews for that book.

So, there are many things going on here.

• Priorities, which leads you into getting knowledge hopefully.
• Knowledge, which leads you into being aware hopefully.
• Awareness, which allows you to spot crazy stuff such as nonsense reviews hopefully.

The original question here was “What are user generated content for if they are so crap?”.

Supposing that people who have that awareness can easily decide if a piece of material is good or not without the help of user generated content, then user generated content only serves people without that awareness. Those cannot see whether a piece of user generated content is good or not and they don’t try to because they lack the awareness. Now, the question that pops up inside my head is: Why people without the awareness consider user generated content to be true and not false?

I ask that because it’s what happens most of the times. People could suppose all user generated content are wrong, but they do the opposite. Examples:

• People ask questions in Yahoo! answers.
• People ask questions in Orkut communities.
• People ask for recommendations on twitter.
• People ask for questions in BBS.
• …

I don’t have an answer for that question, but once I’ve read that if something is written and fixed somewhere, it increases dramatically the chances of it to be considered true. User generated content are fixed somewhere (the web page) and are written.

Which makes a lot of sense. Think about it. Try to remember all the times you doubted someone. Now see if it was something written or something spoken. For example, I doubt most of the things I hear.

And that adds more to the table.

• Preconceptions we have of things.

Now, all this creates is a cycle where we get no answers, just more questions. That is fun, but I’ll stop here.

Answering the original question I posted here, I think believing in user generated content is like lottery. It may help you, but there is nothing granted whatsoever. So, it may help with your decisions, but surely there better places to go.

Note: I’ve just noticed that in this post I’ve explained how to spot bad user generated content.

If you just happened to read this post, please comment. Leave your thoughts and, if you will, ask for suggestions.