3 ms·

// Hardware acceleration should be switched off. // Originally we'd planned to use hardware acceleration but later // on in the project's life cycle we were

by lhnz 13y ago

// Hardware acceleration should be switched off. // Originally we'd planned to use hardware acceleration but later // on in the project's life cycle we were told we needed to support older // versions of Foo: X and Y. This caused some bugs documented [here](#123) and [here](#234) // due to incomplete support of feature Z and the way that [internMethod()](#internMethod) is currently implemented. // @TODO: It would be better if we could switch it on or off depending on the device. canvas.enableHardwareAcceleration(true); Comments should be organic and give context. They should describe why and the high-level how, while code should describe what and the the low-level how. That's just my opinion. This is the kind of comment I write. From time to time it becomes incorrect when a project's moving fast, but I write enough that it's very easy to validate that the use cases and code I'm talking about are real. You're meant to delete the comment immediately if it's incorrect: you can choose to help the next person understand the code or not, that's not up to me. I think something that's very important is trying to show where a line of code or method fits in the greater scheme of the architecture of the code by linking it towards the methods that are interrelated in important ways. Edit: You might notice I've left the comment not matching the code. This is a fact of life: somebody will change the code without updating the comment. However, because of the comment you now have a great way of sanity checking this change without having to find the original coder or test it all. Basically: it tells you what you couldn't quickly know looking at uncommented code.

IgorPartola 13y ago
Let's look at some stylized comments I've seen over the years: // Add tax total = price + tax Useless comment, isn't it? // Iterate over the order items for item in order: ... Also useless. for ($i = 0; $i < count(points); $i++) { if (...) { // Break out of the loop $i = 1000000; } } Not as useless as the code below it, but still pretty useless. def add_item(order, item): '''Appends item to order. param order : instance of <Order> param item : instance of <OrderItem> return : None '''' order.append(item) This is a great example of a useless docstring. The developer might as well have put the code into the docstring. # <HACK-ALERT> # The code below uses an undocumented API, that nonetheless we must use in order to make the code work. # As per <link to StackOverflow> and <link to unresolved ticket>, this is a known issue. # We may be able to remove it after release X.Y where the upstream fixes it. Widget._enableDitzelMode(Widget._DITZEL_MODE_FLAG_X) # </HACK-ALERT> This is not only useful, but more or less required. If you do any kind of monkey patching, please add this. # <DANGER> # The code below looks wrong, but is in fact correct. This @#$%ing API makes you say "true" # when you mean "false". Do not alter without reading <link to docs>. # Set PRODUCTION mode to ON. Widget.setStagingMode(true) # </DANGER> This is also pretty much required, I think. // Make sure to use === below since foo can be null OR '' which mean different things for us: if (foo === null) { alert("Value is unknown."); } else { processValue(foo); } I'd say also useful, but the code is going to change eventually.

by lhnz 13y ago

IgorPartola 13y ago

Let's look at some stylized comments I've seen over the years: // Add tax total = price + tax Useless comment, isn't it? // Iterate over the order items for item in order: ... Also useless. for ($i = 0; $i < count(points); $i++) { if (...) { // Break out of the loop $i = 1000000; } } Not as useless as the code below it, but still pretty useless. def add_item(order, item): '''Appends item to order. param order : instance of <Order> param item : instance of <OrderItem> return : None '''' order.append(item) This is a great example of a useless docstring. The developer might as well have put the code into the docstring. # <HACK-ALERT> # The code below uses an undocumented API, that nonetheless we must use in order to make the code work. # As per <link to StackOverflow> and <link to unresolved ticket>, this is a known issue. # We may be able to remove it after release X.Y where the upstream fixes it. Widget._enableDitzelMode(Widget._DITZEL_MODE_FLAG_X) # </HACK-ALERT> This is not only useful, but more or less required. If you do any kind of monkey patching, please add this. # <DANGER> # The code below looks wrong, but is in fact correct. This @#$%ing API makes you say "true" # when you mean "false". Do not alter without reading <link to docs>. # Set PRODUCTION mode to ON. Widget.setStagingMode(true) # </DANGER> This is also pretty much required, I think. // Make sure to use === below since foo can be null OR '' which mean different things for us: if (foo === null) { alert("Value is unknown."); } else { processValue(foo); } I'd say also useful, but the code is going to change eventually.