Self documenting code is not

Here I am, again bashing agile methods…

One of the aspects of the agile development model is that code should be self documenting, so there is no need to write a (proper) documentation.

There is only one problem: self documenting code don’t work. The reason is quite simple: when your code is your document, new developers will get into code before getting the whole picture. Joel Spolsky once complained (correctly) that code is hard to read than write and that’s why we end up (on big projects) with five or more functions that count spaces on strings. Remember when you got your new job, working in the language you always dreamt? Did you remember your excitement and how much do you want to prove you could do it (not only to management, but to yourself)? Well, that’s when you start the process of “five functions that do the same thing”.

That’s why you should never EVER use code as reference. The correct way to develop software is write the API first, documenting it and THEN moving to code. You don’t need to think about how to do what the function will do, but you need to know what parameters it will take and what it will return. This should keep away from the code (you can use some application that can extract special comments with this information, like doxygen or NaturalDocs) and then show this before letting anyone moving into code. Also, it should be easily available all the time, so current developers will know all the available functions and not reinvent the wheel.

Comments are in

Finally, posting comments works. They don’t look good, but I guess it is a better way to give feedback about the current layout. I’m still thinking how to make it look good (as I finally managed to make the display of the current comments work fine.)

Any suggestions are (still) welcomed.

Edit 1: Headings still need work, I know.

Modernizando velhas piadas

<a href=”http://ribeirão/cachaça”>Água</a> -> 404 Not Found
<a href=”http://ribeirinho/água”>Água</a> -> 200 OK

As vozes na minha cabeça me acordaram rindo e me contaram essa…

Eu disse que eu era nerd…

View comments are in and they are ugly

I just managed to add the code to display the comment but not to add comments yet. The reason is that they comments look ugly right now and I don’t have any ideas on how to fix it.

Why they are ugly? Well, WordPress comment_text() function likes to add paragraphs (the <p> tag) around the comment. If I do a multi-line string (like it is today), the quotes end far away from the text, not to mention that it makes navigation confusing, as it is also a multi-line string. If there was a way to turn everything into a comment, it would be cool, but there are line breaks and it would really look weird (although on small screens the comments would break anyway and the browser would not add the hash in front of every line), not to mention that paragraph problem…

Still trying to figure out a good solution for comments before letting more to be added…

Não é spam?

Por algum motivo estranho, eu gosto de ficar olhando os emails que o GMail marca como Spam. Hoje recebi um daquelas propostas milagrosas de ganhar dinheiro sem sair de casa. A parte interessante foi o final:

Mensagem Importante: Nossa mensagem NÃO é SPAM, veja o porquê: O e-mail é uma forma de correspondência igual a uma ligação telefônica ou a uma carta. No Brasil e no resto do mundo, da mesma forma que não é necessário autorização para se mandar cartas ou telefonar para alguém, também é desnecessária autorização prévia para o envio de e-mails. De qualquer forma, não há nada na legislação brasileira que refira-se à prática do SPAM, ou que a regulamente e certamente quando existir apenas tornará obrigatório ao remetente oferecer uma forma de exclusão uma vez que a proibição seria inconstitucional. Se você quiser sair do nosso grupo de mensagem, dê um reply com o tópico REMOVER. Portanto, se você nao quer fazer parte deste grupo de mensagem, bastar retornar este e-mail com o assunto : RETIRAR, que estaremos automaticamente excluindo seu e-mail desta lista.;

Veja só que interessante: só porque tu pode receber ligação de qualquer um, então esse email, que também poderia vir de qualquer um, não é spam! Incrível como a lógica dessas pessoas não consegue ver que Spam vai muito além de email: Receber uma ligação de uma empresa vendendo um produto que não te interessa e com informações que tu nunca pediu É spam; receber toneladas de papel pelo correio (ou aquelas malditas propagandas do banco junto com o extrato) É spam; Heck, até “Santinhos” na época de eleições É spam!. Só porque o meio é eletrônico, não quer dizer que não é spam.

A única questão importante aqui seria porquê brigamos tanto pra não ter spam na nossa caixa de correio virtual e não na nossa caixa postal normal ou no nosso celular ou na rua da cidade. A resposta é simples: custa dinheiro pra encher a rua de santinhos; custa dinheiro fazer uma carta de 10 gramas pesar 150 com o excesso de papel; custa dinheiro fazer uma ligação telefônica. Entretanto, mandar um email de um provedor gratuíto, custa quase nada para quem tá mandando, mas custa pra quem mantêm a internet funcionando.

Ainda torço pelo dia que as pessoas vão ter que ter permissão pra tocar num computador…

Theme updates

In case you didn’t noticed: I merged all links into a single “class” and single posts now have links to previous and next posts/functions.
Also, behind the scenes, I paved the way to finally displaying comments. I’m almost there, I promise. Then, headings and then RELEASE! :)

“I

In case you don’t look at this blog directly (i.e., through RSS): I just put my new WordPress theme “I <3 Python” as default theme for the page. I know that comments are not being displayed and I’ll fix it as soon as possible.

Take a look and send your opinions (you need to send me an email — remember: comments are not working). Suggestions for improvements are also welcome.

Edit 1: Headings are also not working (well, they are, but they are changing the font size). You can check it on the Meta Personal FAQ page.