Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How can I express this more clearly or concisely?

+0
−0

I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on a user input screen. Here's my best shot but it still seems confusing because the 'in the', 'on the', 'for a' seem like a lot of prepositions for one sentence.

This function returns the WINGNUT_SELLER_CODE that appears in the 'Vendor' field  
on the 'THREADED_NUTS' screen for a given NUT_ID. 

Questions:
[1] How can I rewrite this to make it easier to understand?
[2] What about 'that appears' vs. 'which appears' when should I use 'that' and 'which' ?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/3843. It is licensed under CC BY-SA 3.0.

0 comment threads

1 answer

+1
−0

Edited based on comments:

Given the following function declaration:

f_get_vend_code(v_nut_id varchar2) return varchar2;

I would write the description as follows:

This function takes a nut ID (NUT_ID) and returns the vendor's seller code (WINGNUT_SELLER_CODE) for this form. If NUT_ID is not set (blah blah blah). If the function cannot find a valid seller ID it (does something).

Note: I'm using Java idioms because those are the ones I'm familiar with. I'm assuming that "takes (a parameter)" and "returns" are meaningful for your audience too; you should verify that by reading other API documentation for this language. I am also assuming that the values you originally used, e.g. NUT_ID, are meaningful even though they don't appear in the signature; if that's not the case then I would omit them in the description.

Also note that I went beyond your original question to cover invalid parameters and error conditions. Good API documentation goes beyond what they can get from just reading the signature and tells them what they wouldn't be able to figure out otherwise.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »