بسيطة جالبة/اضع تعليقات
https://stackoverflow.com/questions/1028967
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russianسؤال
ماذا الاتفاقية التي تستخدمها التعليق حاصل على واضعي?هذا شيء أنا مستغرب لبعض الوقت ، فعلى سبيل المثال:
/**
* (1a) what do you put here?
* @param salary (1b) what do you put here?
*/
public void setSalary(float salary);
/*
* (2a) what do you put here?
* @return (2b)
*/
public float getSalary();
أجد دائما أنا أكتب نفس الشيء بالنسبة 1a/b 2a/ب شيء مثل 1a) يحدد راتب الموظف ، 1b) راتب الموظف.لقد بدت زائدة عن الحاجة.الآن أستطيع أن أرى شيئا أكثر تعقيدا قد تكتب في (أ) أجزاء ، لإعطاء السياق ، ولكن أغلبية حاصل/واضعي هناك صيغة تقريبا بالضبط نفس الشيء.
أنا فقط فضولي لو بسيط حاصل/واضعي موافق فقط في ملء إما (أ) جزء أو (ب) جزء.
ماذا تعتقد ؟
المحلول
وأنا عادة مجرد ملء الجزء المعلمة لواضعي، والجزءreturn للحاصل على:
/**
*
* @param salary salary to set (in cents)
*/
public void setSalary(float salary);
/**
* @return current salary (in cents, may be imaginary for weird employees)
*/
public float getSalary();
وبهذه الطريقة جافادوك أدوات (مثل تحذيرات الكسوف) فحص سيخرج نظيفة، وليس هناك ازدواجية.
نصائح أخرى
ولا طائل منه على الاطلاق - كنت أفضل حالا بدون هذا النوع من حماقة التبعثر التعليمات البرمجية:
/**
* Sets the foo.
*
* @param foo the foo to set
*/
public void setFoo(float foo);
ومفيدة جدا، إذا اقتضى الأمر:
/**
* Foo is the adjustment factor used in the Bar-calculation. It has a default
* value depending on the Baz type, but can be adjusted on a per-case base.
*
* @param foo must be greater than 0 and not greater than MAX_FOO.
*/
public void setFoo(float foo);
وخصوصا شرح ما يعنيه الملكية في الواقع يمكن أن تكون حاسمة في النماذج المجال. كلما أرى حبة كاملة من الخصائص مع أسماء غامضة أن البنوك الاستثمارية فقط، الكيمياء الحيوية أو علماء فيزياء الكم فهم، وتعليق شرح أن الأسلوب () setGobbledygook "يحدد الهراء."، أريد أن خنق شخص.
وعموما أي شيء، إذا كنت يمكن أن تساعد في ذلك. يجب أن يكون لا تحتاج إلى شرح وحاصل على واضعي.
وأنا أعرف أن يبدو وكأنه غير الجواب، ولكن أنا أحاول أن استخدام وقتي للتعليق الأشياء التي تحتاج إلى شرح.
أنا أقول تقلق فقط عن التعليق حاصل على واضعي إذا كان لديهم نوع ما من تأثير جانبي, أو تتطلب نوعا من شرط خارج التهيئة (أي:الحصول على إزالة عنصر من بنية البيانات ، أو من أجل وضع شيء تحتاج إلى أن يكون x و y في المقام الأول).وإلا التعليقات هنا هي جميلة زائدة عن الحاجة.
تحرير:وبالإضافة إلى ذلك, إذا كنت لا تجد الكثير من الآثار الجانبية تشارك في جالبة/واضع ، قد ترغب في تغيير حاصل/اضع إلى طريقة مختلفة اسم (أي:دفع البوب كومة) [شكرا على التعليقات أدناه]
واسأل نفسك ماذا تريد أن يرى الناس عندما ينظر إلى التعليقات التي JavaDocs (من المتصفح). كثير من الناس يقولون أن الوثائق ليست ضرورية لأنه واضح. هذا لن يعقد إذا كان الحقل الخاص (إلا إذا قمت بتشغيل صراحة على JavaDocs لحقول خاصة).
في قضيتك:
public void setSalary(float s)
public float getSalary()
وليس من الواضح ما المرتبات يتم التعبير فيها ومن سنتا، دولار، جنيه، RMB؟
عند توثيق اضعي / حاصل، وأنا أحب أن فصل ما من الترميز. مثال:
/**
* Returns the height.
* @return height in meters
*/
public double getHeight()
والسطر الأول يقول أنه يعود الارتفاع. وثائق المعلمة عودة أن الارتفاع بالأمتار.
لماذا لا تشمل فقط علامة مرجعية لتمكنك من التعليق على قيمة حقل والإشارة من حاصل واضعي.
/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;
public String getFoo() {
return foo;
}
public void setFoo() {
this foo = foo;
}
وهكذا إلى أن وثائق تنطبق على جالبة واضعة فضلا عن الميدان (إذا تم تشغيل javadocs خاصة في هذا هو).
وهذا النوع من النمطي يمكن تجنبها باستخدام مشروع لومبوك . مجرد توثيق متغير الحقل، حتى لو كان private، والسماح الشروح لومبوك توليد حاصل على واضعي موثقة بشكل صحيح.
أنا بخيبة أمل حقا عن إجابات قائلا أساسا شاملة توثق هو مضيعة للوقت.كيف عملاء API الخاص بك من المفترض أن تعرف أن طريقة تسمى setX هو معيار التخطيط الاستراتيجي المشترك javabean الملكية اضع إلا إذا كنت أقول ذلك بوضوح في وثائق?
دون وثائق ، المتصل لديك أي فكرة على الإطلاق إذا كان أي من الآثار الجانبية الأخرى من خلال عبور أصابعهم عن الظاهر الاتفاقية يجري اتباعها.
أنا متأكد من أنني لست الوحيد هنا كان من سوء حظ لمعرفة بالطريقة الصعبة أن طريقة تسمى setX يفعل الكثير أكثر من مجرد مجموعة من الممتلكات.
إذا لم يكن هناك عملية خاصة في جالبة / اضع أنا أكتب عادة:
ومع جافادوك (مع خيار خاص):
/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);
و / أو
/**
* Get {@see #salary}.
* @return {@link #salary}.
*/
public float salary();
ومع Doxygen (مع خيار استخراج خاص):
/** @param[in] #salary. */
public void setSalary(float salary);
/** @return #salary. */
public float salary();
وتعليقا يمكنهم الدخول، خصوصا إذا كانوا لا يقومون بأي عمليات في أي مكان، لا لزوم لها ومضيعة للأطراف الأصابع.
واذا كان هناك من قراءة التعليمات البرمجية لا يمكن أن نفهم أن person.getFirstName() ترجع الاسم الأول للشخص، يجب أن تحاول كل شيء في الصلاحيات الخاصة بك لتحصل عليه النار. إذا كان كذلك بعض السحر قاعدة بيانات، ويلقي بعض الزهر، يدعو الأمين الأسماء الأولى للحصول على الاسم الأول، ومن الأسلم أن نفترض انها عملية غير تافهة، وتوثيق ذلك جيدا.
إذا، من ناحية أخرى، person.getFirstName() الخاص بك لا يرجع الاسم الأول للشخص ... حسنا، دعونا لا نذهب الى هناك، ونحن؟
لا تضع أي شيء إذا كان اسم الحقل وصفي suficiently من محتويات.
وعموما، والسماح للكود يكون قائمة بذاتها، وتجنب التعليق إذا كان ذلك ممكنا. وهذا قد يتطلب إعادة بيع ديون.
وتحرير: يشير ما سبق إلى حاصل على واضعة فقط. أعتقد أي شيء غير تافهة يجب javadoc'ed بشكل صحيح.
وعلى ما يرام لملء (ب) جزء منه، خاصة إذا كنت وضعت تعليق في إعلان الحقل مشيرا إلى ما هو الحقل كل شيء.
إذا لم جافادوك إضافة أي شيء، أنا حذف جافادوك واستخدام التعليقات الذي تم إنشاؤه تلقائيا.
وأنا دائما ملء على حد سواء. الوقت الذي تستغرقه في الكتابة إضافية لا يكاد يذكر، والمزيد من المعلومات أفضل من أقل بشكل عام.
وإذا كان جالبة / اضع، فإنه يجب أن تكون موثقة.
وهذا ليس موضوعنا هنا، ولكن إذا كان يمكن أن يتم الممتلكات، وربما هذا هو أفضل لالترميز أسهل للمستخدمين من فئة. أنا استطرادا أبعد ولكن كما لجميع التعليقات التي لديها "جافا" في أي مكان في نفوسهم، والذي قال انه كان جافا؟ (العلامات، ولكن السؤال افتقدوا أي مكان حقا)
