Leaderboard

Good comments are not about *what* the code does but *why* because that is typically the question a future reader will have when they read the code. And experience teaches you to anticipate such questions and put comments where appropriate.

As a serious software developer you have to constantly refactor and improve your code.

Even Chuck Norris refactors his code (with a roundhouse kick though but still...)

Code is never perfect. You just revisit code months later and some things will inevitably draw attention. Sometimes, improvements are just minor tweaks, sometimes you are like "what was I thinking, this whole thing has to go". Sometimes, you just leave all the horror untouched because you don't have time. It is a never ending story.

I always remember the Peter Gottschling's description of a program comment from his book "Discovering modern C++":

That's what comments are for. I don't see wisdom or a particularly high level of expertise in the words "Good code needs no comments, it is self explanatory".

Of course comments explaining every line of code are all in all useless. I'm talking about comments informing the uninformed reader what the heck is going on, and why a problem is solved this way and not another (hence preventing aforementioned refactoring odysseys). Most times those comments form the core of my technical file and only need a little fleshing out and graphs to be acceptable for auditors.

Don't worry, I've never seen larger projects, where the code could explain all the thinking behind the tinkering, especially the larger picture. I think we all can agree, that good code explains what it is doing quite well, however, rarely, if ever why and never the reason behind he full logic of a multi-year-project.

There was several cases when I looked and thought "what I was thinking, this stuff is ugly and non-optimal, I'll fix it in a minute", but after N hours of redesigning the code I realized "Aaaaahhh I meant THAT thing!" and reverted old code but now prepending it with extensive comments entitled with "There be dragons" magic phrase xD

I've been using Delphi for 25 years, I'm working on a 20 year old code base, I'll let you know when I'm done refactoring

Nope, that would be an array of unsafe references - an important characteristic of a weak reference is that it will be cleared when the referenced instance gets destroyed. Since you cannot declare TArray<[weak]IInterface> or something like that you need to make a record type with a weak reference field. Since Object ARC will be history with 10.4 I don't care - but weak reference for interfaces will still be a thing: {$APPTYPE CONSOLE} uses System.SysUtils; type weakref = record [weak] ref: IInterface; class operator Implicit(const value: IInterface): weakref; inline; class operator Implicit(const value: weakref): IInterface; end; class operator weakref.Implicit(const value: IInterface): weakref; begin Result.ref := value; end; class operator weakref.Implicit(const value: weakref): IInterface; begin Result := value.ref; end; procedure Test; var refs: TArray<IInterface>; weaks: Tarray<weakref>; intf: IInterface; begin SetLength(refs, 3); refs[0] := TInterfacedObject.Create; refs[1] := TInterfacedObject.Create; refs[2] := TInterfacedObject.Create; SetLength(weaks, 3); weaks[0] := refs[0]; weaks[1] := refs[1]; weaks[2] := refs[2]; refs := nil; Writeln(Assigned(IInterface(weaks[0]))); Writeln(Assigned(IInterface(weaks[1]))); Writeln(Assigned(IInterface(weaks[2]))); end; begin Test; end. FWIW Spring4D has Weak<T> that works for interfaces and objects and has the added feature that when used for objects on non ARC platform it also clears then and thus protects against dangling references.

It is a non stop optimizing and refactoring ... Never ending story 😉

I believe Stefans words to be a fitting final statement on the subject of comments and suggest veering back to the subject at hand...namely refactoring 😉

Some interesting implementations, thanks. Not sure that I can use any of them though.

It all depends on the definition of "good code". Of course my code is good code. 😉 The advantage of code without comments is that you don't have to worry about the comments being wrong or outdated because the code was changed (fixed) and nobody bothered with the comments because the code compiles anyway. And of course there are those absolutely unnecessary comments like: // for all 50 entries for i := 1 to 50 do begin // process the entry process(entry[i]); end; // we are done processing all entries But some programmers (and managers) still insist that these kinds of comments are necessary and a sign of a well documented code base. I definitely disagree here. But I think we degress.

I certainly am not a Delphi expert in the sense that I don't make mistakes and always produce perfect code. (And as I just yesterday noticed (again) some of my "knowledge" about Delphi is outdated or even has been wrong in the first place). So, I don't really qualify for answering this question even though I have been working with Delphi for nearly my whole professional life. But here goes anyway: I'm never done improving or fixing even my own code base. And don't get me started on the code base of the company I work for. We still have code that is at least 15 years old and has never been refactored even though it is in dire need for that. It's improving slowly but I doubt that it will ever be up to even my standards.

@Vincent Parrett Done yet? 😄 Honestly, refactoring does not only mean fixing and improving code itself, though, as stated above, as learning and evolving creature, there is always a chance for that, no matter how expertly you done it, but requirements change, features need to be implemented, and so on. Existing code may anticipate a lot of upcoming changes, but ever everything? So yes, there will always be a need for refactoring. Now, let's go back to my last paragraph and do that 😉

Much of the development I do is refactoring. Not for its own sake, but to enable a new development. Typically this means refactoring existing code, relying heavily on the testing of that code, so that the new development can be added easily. Often the bulk of the time is spent refactoring and then the new development is trivial. In other words, even when code is well factored, it often needs to be refactored. Also, its not at all the case that replacing standalone functions with classes always makes your code better. Don't be afraid to have standalone functions if that is the right design.

AFAIK, that has been true for Windows 95. According to the WinApi SetTimer function, which is internally used by a VCL TTimer, the minimum value for Interval is 10 ms:

My book Hands-On Design Patterns with Delphi covers a Pipeline pattern which I fully implemented in PPL. It may give you some ideas on how to approach your problem. The source code is freely available on GitHub.

https://github.com/hunspell/hunspell/blob/master/src/hunspell/hunspell.h contains about 10 functions, one of the most short APIs I ever seen xD