Sunday, October 21, 2012

Source Code Commenting?

A little history

Over the years, my view on commenting source code has changed substantially. As an immature developer, I believed that it was worthwhile to comment the code in such a way as you could tell what the code was doing simply by reading the comments. This was my philosophy, and I followed in judiciously.

Why I changed (grew up?!)

There are two major problems with this.

1. Change.

Changes to the source require changes to the comments.

But this, despite what some would say about ‘don’t be lazy and just update the comments’, is much more difficult than simply ‘updating them’.

The real issue is that comments are written in a human context-dependent language.

Think about this for a minute. Here some rudimentary linguistics is quite helpful (and not of the nonsensical Derrida variety).

So what is the issue? The problem here is that meaning is found at the discourse level in human languages. Paragraphs are the real substantial unit of meaning. This means that changes to such commenting are vastly more involved than even changes to their source code. It is like rewriting a paper after changing the thesis, or major point. It isn’t easy to make it coherent.

2. Code can be expressive.

This is nothing new, of course (cf. Bob Martin’s Clean Code). Really, I have become increasingly convinced that anything that can be expressed in code should be. And that really covers almost all of it. We have human-readable languages for just this reason.

One caution come to mind, however: Brevity. Be as brief as reasonably possible. That is, don’t write excessively long camel-case names. Not because it is wrong per se, but because they become hard to read, thus negating their purpose. Use the context of the code. Interestingly, this runs into the same tension as point (1) above, since you begin to have “discourse level” interdependencies in the code.

The problem is that you cannot include all the surrounding levels of abstraction in the function name. If you do, it becomes too cumbersome to be realistically maintainable. However, this runs into the tension of context-dependent function names.

The key here is to make sure that every name actually exists at one level of abstraction, in my view, and to make sure that you’re applying dependency inversion judiciously. Then you can have sufficiently long names that don’t get either too cluttered, or so obscure as to be useless.

Work to become more expressive with English. Learn how to compress thoughts. Here’s a way to practice this. Write a five page essay on some topic, and then try to say the same thing in three pages.

With that said, where do I think we need comments?

The first thing that comes to mind is APIs. But I want to suggest that this is a red herring. APIs need commenting for a particular reason, in my view: Leaky abstractions.

’m beginning to wonder if this category couldn’t encompass all necessary commenting. The very nature of a leaky abstraction is, bearing with my tautological explanation, that an underlying, concealed, abstracted implementation can or will affect the behavior of the abstraction in a way that is not obvious at that level of abstraction.

So if I have two phones, and one of them is a cell-phone, and the other a sat-phone, the former will work in tunnels (most of the time), but the latter will certainly not. The underlying implementations leak through and affect the usage and behavior of a potentially common user interface.

You need to understand something about the implementation to know whether you can have a crucial call when you’re about to go underground for a while.
This is where comments are truly useful.

Of course, if we take any class or API, it may not be obvious how one should go about using the functionality; e.g. What do I call first?

However, I think that well-written tests are far better than commenting here. Why not ship your acceptance tests with your product? They should be human-readable, and they aren’t just an instruction manual. They are “examples” and “instructions” that actually self-verify. This can’t but help everyone involved.
Happy engineering!

Monday, October 1, 2012

The Zenbook Prime (UX31A): A stunning product with a few significant flaws

(Note: I have also posted this review here).
This UX31A is a beautiful machine. Note that the R7202F is a UX31A-1AR4. It is roughly akin to a DB71, but it lacks a TPM, and has Windows Home Premium. It has an i7 1.9 GHx, dual core, quad-thread processor.
It looks far sharper than any Apple (in my view), and its construction is solid. It is light, sturdy, and it runs cool (the CPU runs at around 40 Celsius under normal conditions, and all the warmth is centre, above the keyboard). The IPS display is beautiful, and is perfectly visible in direct sunlight. Its brightness vastly exceeds other machines in its class. It is simply the best display in its class, bar none. The colours are incredible. The audio quality seemed quite good to me, though I'm no audio expert.
This machine has DDR3-1600, not 1333, as posted in many descriptions (I confirmed that it is dual channel @ 800 MHz). The one I received came with a Sandisk SSD (more on this later).
The battery life ranged from 5 hours (full bright, wifi on, backlit keyboard on) to 9-10 hours (low bright, wifi off, backlight off).
On the negative side:
1. The screen has some backlight bleeding. This is common on IPS screens, but if you need perfect blacks and watch a lot of movies on it, you might notice it. It isn't visible in normal use. Mine bled on the bottom right rather noticeably on a full black screen. This isn't a big deal for me. It is a shame, though.
2. The keyboard seems to miss keystrokes now and then. I don't think this was just me; other ASUS users encountered this on their machines. It occurs when typing very quickly. However, the keyboard is otherwise nice to use.
[Note that my second UX31A was much better on this point.]
3. The touchpad is unusable out of the box. The latest beta driver on the ASUS site gets it working well enough. You may need to disable tap to click as well; this is commonly an irritation on touchpads, because you can 'click' with your palm while typing. Note that if you need more configuration of your touchpad, Samsung has a driver which will run on the Zenbook Prime's touchpad, which also corrects the issues.

[Edit: Do not install the 1.0.32 driver, as it is about as bad as it gets -- it doesn't correctly reject palm contact, and it does reject normal finger contact. It is next to unusable. ASUS ought to try out their software before the ship it. The 1.0.26 beta driver works well enough.]

4. The unit I received would randomly shut down a few minutes out of sleep, every once in a while. This wasn't a bluescreen. There is no data in the Windows logs about the shutdown. Odds are, the machine lost power somehow. It happens whether the notebook is plugged in or not. This is a serious problem.
[See here.]
5. The Sandisk SSD is slow in small reads and writes. As in, it is terrible (4 MB/sec in some cases). I confirmed this myself. The alternative AData drive that comes in this laptop when there is stock is reportedly much better. That said, the computer ran fast. Most would probably not notice this.
6. There is too much Junkware on it. I removed the Trendmicro trial, the ASUS cloud stuff, and a few other trials. Just install Microsoft Security Essentials and be done with. When the antivirus makers can produce software that doesn't act like the malware they try to stop, we can use it.
Overall, this was a really nice machine. Some of those flaws are bad, but hopefully ASUS works them out soon.
I would have given this full marks for quality, except for the keyboard, mouse, and shutdown issue.

Zenbook Prime and the Unexpected Shutdown Problem

Problem Description

Zenbook Prime ( UX31A) users may notice the computer occasionally turning off without warning. The shutdown is unexpected, sudden, and there is no blue screen / stop code in Windows.
Users will find an event similar to the following in the Windows event log:
Log Name: System
Source: Microsoft-Windows-Kernel-Power
Date: 9/26/2012 12:10:38 PM
Event ID: 41
Task Category: (63)
Level: Critical
Keywords: (2)
Computer: BLAH
The system has rebooted without cleanly shutting down first. This error could be caused if the system stopped responding, crashed, or lost power unexpectedly.
This is a common problem with Zenbook Primes, and it has been for months. There is no software that can bypass the Windows shutdown process. The unit is losing power suddenly. ASUS has not found a solution, and I doubt that they are trying all that hard.
This happens whether the battery is charged, and whether it is plugged in or not. It is rare (my machine did it once in two weeks).
Notably, on a previous UX31A (this is my second; I returned the first on account of this problem), it did it twice in two weeks. So I bought two separate UX31A’s, both with the problem. What are the odds? Quite good, if it is a universal, systematic problem, which I suspect that it is.

Specific Observations

I have consistently noticed that the problem (twice on the other UX31A, once on this one), happens within about 5 minutes of waking from sleep. This one happened at pretty much exactly 4 minutes after waking.
The previous system shutdown at 11:47:44 AM on ‎9/‎26/‎2012 was unexpected.
The system resumed from sleep at: 9/26/2012 11:43:45 AM
This, I think, is telling. I suspect it has to do with power regulation coming out of sleep.

Attempted Workaround

The Ubuntu guys have said this about sudden shutdowns - "RC6 on and Intel IOMMU off."
Status: Specific issue noted above may be safely ignored.
Intel RC6 causes sudden shutdowns (Solved)
Kernel developers are aware and working on an issue with DMAR+RC6.
However, Zenbboks experience sudden shutdowns with RC6 on and Intel IOMMU off.
The most stable configuration is to enable semaphores and turn off VTd in BIOS, see above.
However, this needs to be properly fixed in the kernel once RC6 gets enabled by default.
I have disabled VT-d in the BIOS, along with Intel’s shutdown power management. I have not yet seen the shutdown problem. Note that you don’t need VT-d, as it is a virtualization technology, and it is doubtful that most people will use that on an ultrabook with 4GB of RAM.
Zenbook users who have the shutdown problem – please try this, and let me know in the comments if you still see the shutdown problem.


Honestly, ASUS should have a public statement on their website indicating that it is a known problem, and explaining that they are working to fix it. Their boast of reliability is quite questionable at this point. That, and their service is just wretched. Their website doesn’t work well, their live chat doesn’t work at all (for me), they take too long to reply, and an RMA will take your laptop away for weeks on end. It really is unacceptable. But ASUS doesn’t ‘get it’, and that’s why they keep doing this.
This expresses the issue well:
My overall conclusions with this experience are that if I need customer service, calling the telephone service line is my best bet to get adequate and prompt help. Apparently customer service representatives must go through a list of set actions (resulting in multiple callbacks) before an RMA will be issued. Any sort of online technical support (e-mail or chat) seems useless and unhelpful. Most of the phone representatives seem friendly and helpful.
The laptop RMA service is performed within an adequate time frame (2 weeks, taking into account 6-8 days total for shipping to and from the service center), although the quality control of products leaving the service center seems subpar (did they really check that my laptop was fixed before sending it back to me?).
ASUS products still have a ways to go in terms of quality check prior to product shipment to match up to Apple standards. To be honest, as much as I like the Zenbook and PC’s, I’m not sure I would buy another $1000 laptop from ASUS again after this. It seems absurd that for a brand new laptop, I have to go through numerous phone calls and a month or more of back and forth before things are back to the way they should have been when I first purchased the laptop (let’s hope it stays that way).
Wake up, ASUS!

[Edit: Please read the comments. This approach does not seem to work.]

[Edit: It seems that disconnecting and reconnecting the battery has had some success for various Zenbook users. Note that this will void the warranty (which is nothing other than absurd, but be warned).]

[Edit: Perhaps this is an easier trick than reconnecting the battery? Asus tech recommended one commentator "disconnect the power cord and press the power button for 30 seconds, for a battery reset" and then plug it in and let it fully charge.]