In my Telerik article, Generating Documentation with JustCode, I used the StoryService in Kigg as my example. The initial xml comments that were generated looked kind of funny… why is that?

/// <summary>
/// Promotes the specified the story.
/// </summary>
/// <param name="theStory">The story.</param>
/// <param name="byUser">The by user.</param>
/// <param name="fromIPAddress">From IP address.</param>
public virtual void Promote(IStory theStory, IUser byUser, string fromIPAddress)
{
    Check.Argument.IsNotNull(theStory, "theStory");
    Check.Argument.IsNotNull(byUser, "byUser");
    Check.Argument.IsNotEmpty(fromIPAddress, "fromIPAddress");

    using(IUnitOfWork unitOfWork = UnitOfWork.Begin())
    {
        if (theStory.Promote(SystemTime.Now(), byUser, fromIPAddress))
        {
            _eventAggregator.GetEvent<StoryPromoteEvent>()
                            .Publish(new StoryPromoteEventArgs(theStory, byUser));

            unitOfWork.Commit();
        }
    }
}

The summary became “Promotes the specified the story.” This is due to the first parameter containing an article at the beginning.

It should go without saying that including the article adds no value to that name. One can make the argument that the prepositions on the second and third parameters do, but I would argue that they are implied by being secondary parameters.

I better signature would look like this.

public virtual void Promote(IStory story, IUser user, string ipAddress)
{
    Check.Argument.IsNotNull(story, "story");
    Check.Argument.IsNotNull(user, "user");
    Check.Argument.IsNotEmpty(ipAddress, "ipAddress");

    using(IUnitOfWork unitOfWork = UnitOfWork.Begin())
    {
        if (story.Promote(SystemTime.Now(), user, ipAddress))
        {
            _eventAggregator.GetEvent<StoryPromoteEvent>()
                            .Publish(new StoryPromoteEventArgs(story, user));

            unitOfWork.Commit();
        }
    }
}

Since the primary parameter is story, Promote acts upon it, meaning it is the noun to be promoted. The other two parameter are secondary to this fact, providing information on the user that promoted the story and the IP address that sent the request.

In a nutshell, the articles and prepositions were clutter. Remove them.

However, you would use prepositions to differentiate similar parameters such as fromUser and toUser. The principle is to keep extraneous information out of your names. They should be clear and concise.