[MS] API naming principle: If there is no direct object, then the direct object is the source object - devamazonaws.blogspot.com

It is a common practice that method names begin with a verb: widget.Toggle(), widget.Set­Color(), widget.Get­Associated­Doodad().

Often, the verb is followed by a direct object: widget.Set­Color(), widget.Get­Associated­Doodad(). The direct object is the thing that the verb operates on or produces. In the case of Set­Color, it is setting the color. In the case of Get­Associated­Doodad it is getting the associated doodad.

Sometimes, the verb is not followed by a direct object at all, such as the widget.Toggle() method above. In that case, the direct object is the source object: The widget. In the above example, widget.Toggle() toggles the widget.

<P< All of this may sound obvious, but it's easy to lose sight of this principle.

For example, a team proposed an API with a Widget­Notification and a method widget­Notification.Delete(). As written, it sounds like this deletes the widget notification itself, but the intention was for this to delete a notification listener. The methods for creating and deleting listeners should be named something like widget­Notification.Create­Listener() and widget­Notification.Delete­Listener().

As another example, the name of the Application­Data­Manager.Create­For­Package­Family method doesn't say what it's creating, so the assumption is that it creates an Application­Data­Manager. But that's not what it creates. It actually creates an Application­Data object. The method should more properly be named Application­Data­Manager.Create­Data­For­Package­Family.

An exception to this rule is factory objects. The purpose of factory objects is to create things, so a Widget­Factory.Create() method is assumed to create a widget. But I wouldn't complain if you called your method Widget­Factory.Create­Widget(), just to be clear about it.


Post Updated on July 24, 2024 at 03:00PM
Thanks for reading
from devamazonaws.blogspot.com

Comments

Post a Comment

Popular posts from this blog

[MS] Pulling a single item from a C++ parameter pack by its index, remarks - devamazonaws.blogspot.com

In my earlier discussion of pulling a single item from a C++ parameter pack by its index , I noted that with the Pack Indexing proposal, you would be able to write this to pull an item from a parameter pack while preserving its reference category. template<int index, typename...Args> void example(Args&&... args) { auto&& arg = (Args...[index]&&)args...[index]; using Arg = Args...[index]&&; } Why did I need to apply the (Args...[index]&&) cast ? Why can't I just write this: auto&& arg = args...[index]; or possibly decltype(auto) arg = args...[index]; Well, when you write the name of a variable, the result is an lvalue reference, even if the variable is an rvalue reference . Watch: struct S { S(S&); // construct from lvalue S(S&&); // construct from rvalue }; void whathappens(S&& s) { S t = s; // which will it use? } Try it out in your favorite compiler. This code construc...
Read more

[MS] Boosting Azure DevOps Security with GHAS Code Scanning - devamazonaws.blogspot.com

Image
Debjyoti Ganguly shares insights on the security benefits and configuration of GHAS Code Scanning with Azure DevOps. Boosting Azure DevOps Security with GHAS Code Scanning Code scanning, a pipeline-based tool available in GitHub Advanced Security, is designed to detect code vulnerabilities and bugs within the source code of ADO (Azure DevOps) repositories. Utilizing CodeQL as a static analysis tool, it performs query analysis and variant analysis. When vulnerabilities are found, it generates security alerts. CodeQL CodeQL is a powerful static analysis tool used for showing vulnerabilities and bugs in source code. It enables developers to write custom queries that analyze codebases, searching for specific patterns and potential security issues. By converting code into a database format, CodeQL allows for sophisticated, database-like queries to detect flaws. CodeQL in Action 1. Preparing the Code Create a CodeQL Database : Extract and structure the code into a database for analy...
Read more

[MS] Going beyond the empty set: Embracing the power of other empty things - devamazonaws.blogspot.com

The empty set contains nothing. This sounds really silly, but it's actually really nice. The Windows Runtime has a policy that if a method returns a collection (such as an IVector ), and the method produces no results, then it should return an empty collection, rather than a null reference . That way, consumers can just iterate over the collection without having to deal with a null test. For example, suppose you have a method Widget:: Get­Associated­Doodads which returns an IVectorView<Doodad> representing the Doodad objects that have been associated with a Widget object. If no Doodad s have been associated with the Widget , then it should return an empty vector, not a null pointer. That allows developers to write the natural-looking code: // C# foreach (var doodad in widget.GetAssociatedDoodads()) { ⟦ process each doodad ⟧ } // C++/WinRT for (auto&& doodad : widget.GetAssociatedDoodads()) { ⟦ process each doodad ⟧ } // JavaScript widget.GetAssociated...
Read more